Write custom code using API providers

This is the developer guide for the Support SDK v1 for Android. For Support SDK v2, see Support SDK v2 Android.

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 a valid identity.
  • You can use the following API providers:
    • RequestProvider
      • 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
    • 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.

SafeZendeskCallback

If your callbacks are updating the UI it's important that the current activity or fragment is still valid. SafeZendeskCallback is an extension of ZendeskCallback which can be cancelled when the activity or fragment is paused.

private SafeZendeskCallback<Request> mRequestCallback;
private TextView mTextView;
private TextView mErrorView;

@Override
protected void onResume() {
    super.onResume();

    ZendeskCallback<Request> requestCallback = new ZendeskCallback<Request>() {
        @Override
        public void onSuccess(Request request) {
            mTextView.setText(request.getDescription());
        }

        @Override
        public void onError(ErrorResponse errorResponse) {
            mErrorView.setText(errorResponse.getReason());
        }
    };

    // Wrap the callback in a SafeZendeskCallback
    mRequestCallback = SafeZendeskCallback.from(requestCallback);
}

@Override
protected void onPause() {
    super.onPause();

    // Cancel the callback so we don't attempt to update the UI when the fragment or activity is out of scope
    mRequestCallback.cancel();
    mRequestCallback = null;
}

RequestProvider

Create a RequestProvider as follows:

RequestProvider provider = ZendeskConfig.INSTANCE.provider().requestProvider();
Create a request (ticket)

Example: Use createRequest() to create a new 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

Example: Use createRequest() to create a new request with an attachment

In the following example, {attachmentToken} should be replaced by 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. 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 core API or by side-loading it in the ticket api. Here is 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 which can be used to add custom fields to a request. Custom fields can be added in the Zendesk Support admin interface. Each custom field you add has an ID which is displayed when you view the field in the Zendesk Support admin interface and you will need 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 at HelpCenterProvider.

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.