API providers reference

API providers reference

API providers allow you to use all the features of the Support SDK without the UI. They let you interact with Zendesk 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 the SDK, including providing a valid identity.
• You can use the following API providers:
  • RequestProvider
    • Fetch a list of requests and create new requests
    • Used to fetch a list of comments for a given request and to add additional comments
  • HelpCenterProvider
    • Used to fetch categories, sections, and articles
    • Used to search for articles
    • Used to vote on articles
  • UploadProvider
    • Used to upload attachments
    • Used to delete attachments
  • UserProvider
    • Used to add or remove end-user tags
    • Used to set user-fields to an end-user
  • PushRegistrationProvider
    • Used to register and unregister clients for push notifications
    • Supports webhook and Urban Airship
• API providers return a result asynchronously through a callback provided in a request.
• On success, onSuccess(T result) is called containing the result of type T object. On failure, onError(ErrorResponse error) passes the error that occurred. If a calling context is destroyed before the request is completed, you won't receive a callback.

RequestProvider

Get an instance of the RequestProvider as follows:

RequestProvider provider = ZendeskConfig.INSTANCE.provider().requestProvider();

Create a request (ticket)

The following example uses the provider's createRequest() method to create a request:

CreateRequest request = new CreateRequest();

request.setSubject("Ticket subject");
request.setDescription("Ticket description");
request.setTags(Arrays.asList("printer", "fire"));

provider.createRequest(request, new ZendeskCallback<CreateRequest>() {
    @Override
    public void onSuccess(CreateRequest createRequest) {
        // Handle the success
    }
    @Override
    public void onError(ErrorResponse errorResponse) {
        // Handle the error
        // Log the error
        Logger.e("MyLogTag", errorResponse);
    }
});

Create a request (ticket) with an attachment

The following example uses createRequest() to create a request with an attachment.

In the example, replace {attachmentToken} with an actual attachment token retrieved from uploadAttachment() in the UploadProvider.

CreateRequest createRequest = new CreateRequest();

createRequest.setAttachments(Arrays.asList("{attachmentToken}"));

createRequest.setSubject("Ticket subject");
createRequest.setDescription("Ticket description");

provider.createRequest(createRequest, new ZendeskCallback<CreateRequest>() {
    @Override
    public void onSuccess(CreateRequest result) {
        // Handle success
    }

    @Override
    public void onError(ErrorResponse error) {
        // Handle error
    }
});

The RequestProvider has many more methods. See RequestProvider in the Javadoc. Using them is very similar to the examples above.

Sending additional data in a request

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

Using metadata

The CreateRequest class has a void setMetadata(Map<String, String> metadata) method that can be used to add metadata to Requests. See setting metadata in the core API documentation for more details about metadata.

Here is an example of how to set some metadata on a request. In the example the keys of the metadata are "time_spent" and "account" and the values are "4m12s" and "integration".

CreateRequest createRequest = new CreateRequest();

createRequest.setSubject("Subject");
createRequest.setDescription("Description");

HashMap<String, String> metadata = new HashMap<String, String>() {{
    put("time_spent", "4m12s");
    put("account", "integrations");
}};

createRequest.setMetadata(metadata);

RequestProvider requestProvider = ZendeskConfig.INSTANCE.provider().requestProvider();

requestProvider.createRequest(createRequest, new ZendeskCallback<CreateRequest>() {
    @Override
    public void onSuccess(CreateRequest createRequest) {
        Logger.i(LOG_TAG, "Request created...");
    }

    @Override
    public void onError(ErrorResponse errorResponse) {
        Logger.e(LOG_TAG, errorResponse);
    }
});

You can retrieve metadata using the Ticket Audits API or by side-loading it with the Tickets API. Here's a snippet of the API response from the Audits API showing the metadata in metadata -> custom -> sdk

{
   "audits":[
      {
         ...
         "metadata":{
            "custom":{
               "sdk":{
                  "account":"integrations",
                  "time_spent":"4m12s"
               }
            },
         },
         ...
      }
   ],
   ...
}

Using custom fields and custom forms

The CreateRequest class has a void setCustomFields(List<CustomField> customFields) method that you can use to add custom fields to a request. Custom fields can be added in the Zendesk Support admin interface or API. Each custom field has an ID that's displayed when an admin views the field in the Zendesk Support admin interface. Ask a Support admin to note down this ID to use it in the Support SDK. Custom fields must be visible and editable for end users to work with the Support SDK.

Here is an example of how to set a custom field:

CreateRequest createRequest = new CreateRequest();

createRequest.setSubject("Subject");
createRequest.setDescription("Description");

List<CustomField> customFields = new ArrayList<CustomField>() {{

   Long customFieldId = 1234567L;
   String customFieldValue = "Android 5.0";

   CustomField androidVersionCustomField = new CustomField(customFieldId, customFieldValue);

   add(androidVersionCustomField);
}};

createRequest.setCustomFields(customFields);

RequestProvider requestProvider = ZendeskConfig.INSTANCE.provider().requestProvider();

requestProvider.createRequest(createRequest, new ZendeskCallback<CreateRequest>() {
    @Override
    public void onSuccess(CreateRequest createRequest) {
        Logger.i(LOG_TAG, "Request created...");
    }

    @Override
    public void onError(ErrorResponse errorResponse) {
        Logger.e(LOG_TAG, errorResponse);
    }
});

If your Zendesk Support instance supports custom forms, you can specify the form that will be shown with the void setTicketFormId(Long ticketFormId) method in the CreateRequest class. Here is an example:

CreateRequest createRequest = new CreateRequest();

createRequest.setSubject("Subject");
createRequest.setDescription("Description");
createRequest.setTicketFormId(1234567L);

RequestProvider requestProvider = ZendeskConfig.INSTANCE.provider().requestProvider();

requestProvider.createRequest(createRequest, new ZendeskCallback<CreateRequest>() {
    @Override
    public void onSuccess(CreateRequest createRequest) {
        Logger.i(LOG_TAG, "Request created...");
    }

    @Override
    public void onError(ErrorResponse errorResponse) {
        Logger.e(LOG_TAG, errorResponse);
    }
});

HelpCenterProvider

Using the HelpCenterProvider is very similar to using the RequestProvider. You can call the following methods from the list in HelpCenterProvider in the Javadoc.

UploadProvider

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

UserProvider

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

PushRegistrationProvider

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