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 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 * Used to fetch a list of requests and to create new requests * Used to fetch a list of comments for a given request and to add additional comments

ZDKHelpCenterProvider * Used to fetch categories, sections, and articles * Used to search for articles * Used to vote on articles

ZDKUploadProvider * Used to upload attachments * Used to delete attachments

ZDKUserProvider * Used to add or remove end-user tags * Used to set user-fields to an end-user

ZDKPushProvider * Used to 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
Viewing the API provider documentation in Xcode

You can view all API provider documentation in Xcode by using the open quickly command (shift+command+O) and typing the name of the API provider that you're interested in:

Viewing the API provider documentation on GitHub

You can view all API provider documentation on Github by typing t and typing the name of the API provider that you're interested in. ZDKPushProvider and ZDKUserProvider are defined in ZendeskCoreSDK-Swift.h.

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
    }
}];
Sending additional data in a request

You can send additional data in a request using custom fields.

Using custom fields and custom forms

The ZDKCreateRequest class has a customTicketFields array property that you can use to set the values of custom fields in requests. The actual custom fields are created in the Zendesk Support admin interface. Each custom field has an ID that's displayed when an admin views the field in the Zendesk Support admin interface. You'll need this ID to use it in the Support SDK. Note: Custom fields must be visible and editable for end-users to work with the Support SDK. If your custom field value has multiple words, then the value passed in to ZDKCustomField should be snake_cased.

Here's an example of setting a custom field:

Swift

let customeFieldOne = ZDKCustomField(fieldId: 1234567, andValue: "3")
let customeFieldTwo = ZDKCustomField(fieldId: 2345678, andValue: "some_text")

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

Objective-C

ZDKCustomField *customeFieldOne = [[ZDKCustomField alloc] initWithFieldId:@(1234567) andValue:@"3"];
ZDKCustomField *customeFieldTwo = [[ZDKCustomField alloc] initWithFieldId:@(2345678) andValue:@"some_text"];

 ZDKCreateRequest *request = [ZDKCreateRequest new];
request.customTicketFields = @[customeFieldOne, customeFieldTwo];
[[ZDKRequestProvider new] createRequest:request withCallback:nil];

If your Zendesk Support instance supports custom forms, you can specify the form that will be shown in the agent interface with the ticketFormId property in the ZDKCreateRequest class. 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.