Working with API providers

Working with API providers

API providers allow you to use all the features of the Support SDK without the UI. They let you interact with Zendesk Support on behalf of an end-user.

Before you start

Before you start, the following information is useful to know:

• All API providers assume that you have correctly initialized Zendesk and Support, including setting a valid identity
• API providers return a result asynchronously through a callback provided in a request
• Each callback block contains an NSError parameter that is nil for successful API requests

Available providers

ZDKRequestProvider

• Fetch a list of requests and create new requests
• Fetch a list of comments for a given request and add additional comments

ZDKHelpCenterProvider

• Fetch categories, sections, and articles
• Search for articles
• Vote on articles

ZDKUploadProvider

• Upload attachments
• Delete attachments

ZDKUserProvider

• Add or remove end-user tags
• Set user fields to an end user

ZDKPushProvider

• Register and unregister clients for push notifications
• Supports webhook and Urban Airship

Viewing the API provider documentation

You can view the documentation for the following providers in Xcode or on GitHub.

• ZDKRequestProvider.h
• ZDKHelpCenterProvider.h
• ZDKUploadProvider.h
• ZDKAttachmentProvider.h
• ZDKPushProvider.h
• ZDKUserProvider.h

To view the documentation in Xcode

• In Xcode, use the Open Quickly shortcut (Shift + Command + O) and type the name of the API provider you're interested in.

To view the documentation on GitHub

1. Go to the Support SDK IOS repo on Github.
2. Type t and then type the name of the API provider you're interested in.

Note: ZDKPushProvider and ZDKUserProvider are defined in ZendeskCoreSDK-Swift.h. With Support Providers SDK version 7.0.0 and later and Zendesk Core SDK version 4.0.0 and later, the Objective-C headers for the respective providers are ZDKClassicPushProvider and ZDKClassicUserProvider.

ZDKRequestProvider

Create a ZDKRequestProvider as follows:

Swift

let provider = ZDKRequestProvider()

Objective-C

ZDKRequestProvider *provider = [ZDKRequestProvider new];

Create a support request

After creating a ZDKRequestProvider provider, you can use the provider's createRequest method to create a request.

Swift

var request = ZDKCreateRequest()
request.subject = "My printer is on fire!"
request.requestDescription = "The smoke is very colorful."
request.tags = ["printer", "fire"]

provider.createRequest(request) { result, error in
}

Objective-C

ZDKCreateRequest *request = [ZDKCreateRequest new];

request.subject = @"My printer is on fire!";
request.requestDescription = @"The smoke is very colorful.";
request.tags = @[@"printer", @"fire"];

[provider createRequest:request withCallback:^(id result, NSError *error) {

    if (error) {
        // Handle the error

        // Log the error
        [ZDKLogger e:@"Something went wrong"];

    } else {
        // Handle the success
    }
}];

Create a request with an attachment

You can use the provider's createRequest method to create a request with an attachment.

In the following example, replace UploadResponse with a ZDKUploadResponse retrieved with the uploadAttachment method of the ZDKUploadProvider].

Swift

var request = ZDKCreateRequest()
request.attachments = UploadResponse
request.subject = "My printer is on fire!"
request.requestDescription = "The smoke is very colorful."

provider.createRequest(request) { result, error in
}

Objective-C

ZDKCreateRequest *request = [ZDKCreateRequest new];

request.attachments = @[UploadResponse];

request.subject = @"Ticket subject";
request.requestDescription = @"Ticket description";

[provider createRequest:request withCallback:^(id result, NSError *error) {

    if (error) {
        // Handle the error

        // Log the error
        [ZDKLogger e:@"Something went wrong"];

    } else {
        // Handle the success
    }
}];

Set custom fields when creating a request

The ZDKCreateRequest class has a customFields array property that you can use to set the values of custom fields in new requests. Though custom fields are visible to end users in the ticket form in the web version of the help center, the fields can't be displayed in the conversational interface of the SDK. However, you can still use the SDK to set the values of custom fields directly.

An admin in Zendesk Support can add custom ticket fields to the default ticket form. A custom field can be visible to agents only or to both agents and end users.

The prerequisites for setting custom ticket fields are as follows:

• The custom ticket field is both visible to, and editable by, end users in the web version of the help center. If your custom field value has multiple words, then the value passed in to CustomField should be snake_cased. A Zendesk admin can confirm or set these settings for you. See Adding a custom ticket field for agents and end-users in Zendesk help

• You have the ticket field's id. To find it, you can use the Ticket Fields API or you can ask a Zendesk admin to get it in Zendesk Support. The admin can get the id on the field's settings page at Admin > Manage > Ticket Fields

Here's an example of setting a custom field:

Swift

let customFieldOne = CustomField(fieldId: 1234567, value: "3")
let customFieldTwo = CustomField(fieldId: 2345678, value: "some_text")
let customFieldThree = CustomField(fieldId: 22334455, value: ["one", "two", "three"])
let customFieldFour = CustomField(fieldId: 11223344, value: true)

let request = ZDKCreateRequest()
request.customFields = [customFieldOne, customFieldTwo, customFieldThree, customFieldFour]
ZDKRequestProvider().createRequest(request, withCallback: nil)

Objective-C

ZDKCustomField *customFieldOne = [[ZDKCustomField alloc] initWithFieldId:@(1234567) value:@"3"];
ZDKCustomField *customFieldTwo = [[ZDKCustomField alloc] initWithFieldId:@(2345678) value:@"some_text"];
ZDKCustomField *customFieldThree = [[ZDKCustomField alloc] initWithFieldId:@(22334455) value:@[ @"one", @"two", @"three" ]];
ZDKCustomField *customFieldFour = [[ZDKCustomField alloc] initWithFieldId:@(11223344) value:@(YES)];

ZDKCreateRequest *request = [ZDKCreateRequest new];
request.customFields = @[customFieldOne, customFieldTwo, customFieldThree, customFieldFour];
[[ZDKRequestProvider new] createRequest:request withCallback:nil];

You can also initialize custom fields using a dictionary:

Swift

let customFieldOne = CustomField(dictionary: ["id": 1234567, "value": "3"])
let customFieldTwo = CustomField(dictionary: ["id": 2345678, "value": "some_text"])
let customFieldThree = CustomField(dictionary: ["id": 22334455, "value": ["one", "two", "three"]])
let customFieldFour = CustomField(dictionary: ["id": 11223344, "value": true])

Objective-C

ZDKCustomField *customFieldOne = [[ZDKCustomField alloc] initWithDictionary:@{@"id": @(1234567), @"value" : @"3"}];
ZDKCustomField *customFieldTwo = [[ZDKCustomField alloc] initWithDictionary:@{@"id": @(2345678), @"value" : @"some_text"}];
ZDKCustomField *customFieldThree = [[ZDKCustomField alloc] initWithDictionary:@{@"id": @(22334455), @"value" : @[ @"one", @"two", @"three" ]}];
ZDKCustomField *customFieldFour = [[ZDKCustomField alloc] iinitWithDictionary:@{@"id": @(11223344), @"value" : @(YES)}];

Select a custom form when creating a request

If your Zendesk Support instance supports custom forms, you can use the ticketFormId property in the ZDKCreateRequest class to specify the form that will be shown in the agent interface to display tickets submitted with your app. Here's an example:

Swift

let request = ZDKCreateRequest()
request.ticketFormId = 1333

Objective-C

ZDKCreateRequest *request = [ZDKCreateRequest new];
request.ticketFormId = @(1333);

ZDKHelpCenterProvider

Using the ZDKHelpCenterProvider is very similar to using the ZDKRequestProvider. You can call the following methods from the list at ZDKHelpCenterProvider.

ZDKUploadProvider

Using the ZDKUploadProvider is very similar to using the ZDKRequestProvider. You can call the following methods from the list at ZDKUploadProvider.

ZDKUserProvider

Using the ZDKUserProvider is very similar to using the ZDKRequestProvider. You can call the following methods from the list at ZDKUserProvider.

ZDKPushProvider

Using the ZDKPushProvider is very similar to using the ZDKRequestProvider. You can call the following methods from the list at ZDKPushProvider.