Tickets

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

The conversations you have with your users appear in Support as tickets. Using the Support SDK your users can create new tickets, update existing ones, and receive notifications about updates you make. You can also collect information from your users, directly or in the background, to make it easier to give a useful reply the first time.

On this page:

Note: Some examples in this document specify a view controller instance named navigationController. Example: self.navigationController. You should adapt the snippets to your app. For example, if you use the snippet in a UINavigationController instance, then use self.

Useful information

The UI that is provided with the Support SDK looks like this:

Screenshot: The Help Center in the Support SDK

The Support SDK has several styling options. See Customize the look to learn how to style the interface.

This page is split into sections:

  • Settings tells you what you can configure.
  • Tickets in the Support SDK UI tells you how to get going with the built-in UI.
  • Additional methods tells you how to get going if you want to build your own UI.


Settings

Support admin

Settings for the Support SDK can be found in the admin section of Zendesk Support: Admin > Channels > Mobile SDK

The ability to create tickets with the Support SDK is enabled by default. If you'd like your users to be able to view their tickets and update them, you must enable this feature. Navigate to your app's settings in Support and enable 'Conversations'.

Important: The Essential plan only allows users to create tickets via the Support SDK. Users will not be able to revisit or reply to their tickets in your app, but will be able to receive emails from you.

In your code
Set the subject

You must call the following code before you create a new ticket.

Swift

ZDKRequests.configure { (account, requestCreationConfig) in
    //Set the subject of requests created by the user.
    requestCreationConfig?.subject = "App Ticket"
}

Objective-C

[ZDKRequests configure:^(ZDKAccount *account, ZDKRequestCreationConfig *requestCreationConfig) {
    //Set the subject of requests created by the user.
    requestCreationConfig.subject = @"App Ticket";
}];
Add data to a custom ticket field

Custom ticket fields must be end-user visible and editable. You can set this in the For end-users section of a ticket field's settings.

Custom ticket fields do not have to appear on a ticket form to receive data from the SDK.

To add data to a custom ticket field, you must add it to ZDKConfig before you show the create request screen to your user.

Swift

let customFieldOne = ZDKCustomField(fieldId: 1234567, andValue: "3")
let customFieldTwo = ZDKCustomField(fieldId: 2345678, andValue: "Some text")

ZDKConfig.instance().customTicketFields = [customFieldOne, customFieldTwo]

Objective-C

ZDKCustomField *customFieldOne = [[ZDKCustomField alloc] initWithFieldId:@(1234567) andValue:@"3"];
ZDKCustomField *customFieldTwo = [[ZDKCustomField alloc] initWithFieldId:@(2345678) andValue:@"Some text"];

[ZDKConfig instance].customTicketFields = @[customFieldOne, customFieldTwo];
Add tags to the ticket

You must call the following code before you create a new ticket.

Swift

ZDKRequests.configure { (account, requestCreationConfig) in
    // specify any additional tags desired
    requestCreationConfig?.tags = ["tag_one", "tag_two"]
}

Objective-C

[ZDKRequests configure:^(ZDKAccount *account, ZDKRequestCreationConfig *requestCreationConfig) {
    // specify any additional tags desired
    requestCreationConfig.tags = [NSArray arrayWithObjects:@"tag_one", @"tag_two", nil];
}];
Append additional information to the ticket

You must call the following code before you create a ticket.

Note: Information added in this way will be appended to the body of the ticket. It will be visible to your user.

Swift

ZDKRequests.configure { (account, requestCreationConfig) in
    // add some custom content to the description
    requestCreationConfig?.additionalRequestInfo = "\n\nSome sample extra content."
}

Objective-C

[ZDKRequests configure:^(ZDKAccount *account, ZDKRequestCreationConfig *requestCreationConfig) {
    // add some custom content to the description
    requestCreationConfig.additionalRequestInfo = @"\n\nSome sample extra content.";
}];
Set the ticket form your agent will see

If you would like to specify which ticket form to show when your agent reads tickets, get its ID from your settings (Admin > Manage > Ticket Forms), and use that with the following setting:

Swift

ZDKConfig.instance().ticketFormId = 1333

Objective-C

[ZDKConfig instance].ticketFormId = @(1333);


Tickets in the Support SDK UI

Create a new ticket

This will present a view to your user, where they can add the details of their request, attachments, or provide their email address if it is required.

Swift

ZDKRequests.presentRequestCreation(with:viewController)

Objective-C

[ZDKRequests presentRequestCreationWithViewController:viewController];
Show open tickets

This feature is only available on the Team, Professional, and Enterprise plans.

If you are using an anonymous identity, the end-user will only be able to see requests that have been created on that device. If you are using an anonymous identity and you reinstall the app, requests created on the device before that time will not be shown.

Swift

ZDKRequests.pushRequestList(with: self.navigationController)

Objective-C

[ZDKRequests pushRequestListWithNavigationController:self.navigationController];
Show a single ticket

This component lets your users see an individual ticket and its comments. The following code adds the view controller to an existing and valid navigation controller. The request parameter is a valid instance of a ZDKRequest model.

Swift

let commentsVC = ZDKCommentsViewController(request: request)
navigationController?.pushViewController(commentsVC, animated: true)

Objective-C

ZDKCommentsViewController *commentsVC = [[ZDKCommentsViewController alloc] initWithRequest:request];

[self.navigationController pushViewController:commentsVC animated:YES];
Check for updates on your requests

The ZDKRequestProvider has a method called getUpdatesForDevice which can be used to check if there are any request updates to a user's tickets. This can be used to create a visual indicator for your users when there has been activity on their requests.:

Swift

let requestProvdier = ZDKRequestProvider()
var updatedTickets: [String:Int]?

var requestUpdater = requestProvdier.getUpdatesForDevice { (requestUpdates, error) in
if(requestUpdates?.hasUpdates) != false {
    updatedTickets = requestUpdates?.requestsWithUpdates as? [String : Int]
    }
}

Objective-c

ZDKRequestProvider *requestProvider = [[ZDKRequestProvider alloc] init];
NSDictionary *updatedTickets = [NSDictionary new];

id<ZDKRequestUpdatesProtocol> requestUpdater = [requestProvider getUpdatesForDevice:^(ZDKRequestUpdates *requestUpdates, NSError *error) {
    if (requestUpdates.hasUpdates) {
       updatedTickets = requestUpdates.requestsWithUpdates;
   }
}];

This method caches requestUpdates for up to an hour. Any subsequent calls within that timeframe will return the same cached object without querying the network. Viewing a request will remove it from the cached requestUpdates.requestsWithUpdates object, since the updates have now been seen. This is done when the request's comments load in ZDKCommentsViewController. If you have implemented any custom UI, you can mark a request as seen by calling the following method:

Swift

requestUpdater?.markRequest(asRead: "<request_id>")

Objectiove-c

[requestUpdater markRequestAsRead:@"<request_id>"]

Note: If you have implemented push notifications for tickets, this feature is not available.


Additional methods (API providers)

Create a ZDKRequestProvider

Swift

let provider = ZDKRequestProvider()

Objective-C

ZDKRequestProvider *provider = [ZDKRequestProvider new];
createRequest

Calls a request service to create a request on behalf of the end user.

Name Type Comment
request Request model object.
callback Callback invoked in response to remote API invocation.

Usage:

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
    }
}];
getRequestById

Gets the request specified by the ID.

Name Type Comment
requestId The ID of a request in Zendesk Support.
callback The callback to invoke which will return a ZDKRequest object.
getAllRequestsWithCallback

Gets all requests that user has opened. It will also get an access token if one has not been previously stored. If you are using anonymous identities we will check to see if you have any stored request IDs.

Name Type Comment
callback Invoked in response to remote API invocation
getRequestsByStatus

Filters requests that user has opened by a status. It will also get an access token if one has not been previously stored.

Name Type Comment
status NSString A comma-separated list of status to filter the results by
callback The callback to invoke which will return a list of requests
getCommentsWithRequestId

Gets all comments for a request. It will also get an access token if one has not been previously stored.

Note: Only available on the Team, Professional, and Enterprise plans.

Name Type Comment
requestId NSString requestId Id of a request
callback Callback that will deliver a CommentResponse model
addComment

Add a comment message to a request. It will also get an access token if one has not been previously stored.

Name Type Comment
comment NSString The text of the comment to create
requestId NSString Id of a request to add this comment to
attachments NSArray List of ZDKUploadResponse objects. Can be nil
callback Callback that will deliver a ZDKComment
getTicketFormWithIds

Gets the contents of ticket forms you specify. Only the first 5 ticket form Ids will be fetched.

Name Type Comment
ticketFormIds NSArray<NSNumber*>* An array of ticket form IDs
callback The callback that is invoked when a request is either successful or has an error.