This document discusses the features available in Talkdesk’s SDK.



On a very general level the Callback feature allows your app to seamlessly trigger a contact request to phone number through Talkdesk. A call to the given number will be automatically scheduled to an Agent belonging to your account.

The Callback is actually a generalization of a broader concept: the interaction.

An interaction is a communication of any sort (phone, SMS, mobile, etc.) between a given Talkdesk account and a contact.

Please do note that an interaction can cover different communication channels and that the user reaching the Talkdesk account is defined as a contact.

For the Mobile SDK the most important property in the interaction is its intention. The intention is basically an identifier for the type of interaction. Intentions are separated by Talkdesk account so you can reuse intention names without having any collisions.

The following screencast shows the interaction flow:


Before you start…

Check the Getting Started to find how you can get and set your developer key.

Launching the Callback View Controller

Now that you have everything in place you just need to fire up the InteractionViewController. How you do it will depend on where you want to show it from. You can find several options below.

You need to pass the intention so Talkdesk knows what interaction it will make available to the user.

So, if you want to fire it…

…from a UINavigationController

You just need to push the InteractionViewController into your UINavigationController:

let vc = InteractionViewController(intention: "myIntention")
navigationController?.pushViewController(vc, animated: true)

…as a modal View Controller

You just need to present the InteractionViewController modally from your UIViewController:

let vc = InteractionViewController(intention:"myIntention")
vc.modalPresentationStyle = .FullScreen
presentViewController(vc, animated: true, completion: nil)

…from a UITabBarController

You just need to add the InteractionViewController to your UITabBarController viewControllers:

let myAppViewController = UIViewController()
myAppViewController.title = "My App's View Controller"

let callBackViewController = InteractionViewController(intention:"myIntention")
callBackViewController.title = "Callback"

tabBarViewController.viewControllers = [myAppViewController, callBackViewController]

…from a Storyboard

You just need to drag a new UIViewController to the Storyboard and set its Custom Class to InteractionViewController. Then you can set the Intention name to the proper value also in the Storyboard.

Set the Custom Class:

Custom class

The Module name should be automatically filled by Xcode. If it’s not just set it to TalkdeskSDK.

Set the intention name value:

Intention name

On some (more modern) Xcode versions the TalkdeskSDK module might not be recognized and the Intention Name property might not show up in the Attributes inspector. Should this happen you can still pass the intention name on the Identity Inspector using the User Defined Runtime Attributes. The following screenshot shows how this is done:

Intention name on some Xcode versions

Injecting context data

Note: this feature is not available in Objective-C.

The Callback feature supports injection of customer-related data into Talkdesk. This is a means to make extra information available to the Agent when they call the customer back. Having this capability allows for a better customer experience as the Agent might know beforehand specifics about the customer, their needs or their environment.

Here’s an example:

let vc = InteractionViewController(intention: "callback") { intention in
                    return [
                        "order-number": .text(value: "O2016-10-23443", title: "Order"),
                        "part-ref": .text(value: "SKU-10234", title: "Part Number"),
                        "customer-id": .text(value: "67823", title: "Customer ID")

// present vc as you want

It’s very simple to pass context to Talkdesk. You can simply use the proper InteractionViewController initializer. Besides passing the intention name, you also pass a block that receives the intention name and that returns a ContextualMetadata object. This block is called when the interaction is started so you are fetching your data asynchronously you need to have it available by that time.

The following screenshots show these parameters being displayed on Callbar. The first screen shows the view the Agent will see when the call is ringing and has not yet being accepted. The second image shows the Callbar in call and in the view where the contextual metadata is available:

CBAR calling

CBAR on call

Currently Talkdesk needs to know which fields (name and type) you’ll be passing as Contextual Metadata through the SDK. The field values (content) can change between interactions but the fields names must not and must be known beforehand. This information will be stored on the flow definition and might be different for each flow your account maintains. You don’t need to do anything on your side besides informing us about the field names.

Please do note that at the present moment the injection of context data is not supported via Storyboard. If you need this feature you must use programmatic instantiation as demonstrated above.

Contact form autofill

Note: this feature is not available in Objective-C.

If you have your user data available in your app you can make this information available to the SDK so it can try to autofill the form with that information.

The use case would be supplying your user name and phone number so it would appear prefilled on the form.

The following snippet shows how to do this:

let vc = InteractionViewController(intention: "callback")
vc.interactionController.autofill["name"] = .value(.text("John Smith"))
vc.interactionController.autofill["phone"] = .value(.makePhone("us", number: "55500000"))

You can also pass the interactionController a closure that takes the form item as a parameter and returns the desired autofill value. As an example, the snippet below autofills the name value if and only if it is required:

vc.interactionController.autofill["name"] = .completion { item, _ in
    return item.value.required ? .text("Jenny Smith") : .text("")

Note: The SDK requires that you provide the correct alpha-2 code for the country the phone number belongs to. The number itself should be stripped of the country code so that it is handled correctly by Talkdesk’s routing systems. So if the phone number you want to prefill looks like +155500000, the prefill API would take the following value: .makePhone("us", number: "55500000"), in which the number does not include the country prefix. If you need to perform parsing operations on phone numbers stored as strings, we recommend using Google’s libphonenumber.

The following image shows the form after Name and Phone Number were autofilled:

Form autofill

Please note that the identifiers used by the SDK for the binding are the same ones that have been configured on your Talkdesk flow so be sure to include the correct identifiers. If you need support regarding the field identifiers please contact mobile-sdk-support@talkdesk.com.

Supporting multiple intentions

The Callback feature supports having multiple intentions. This means that you can support different types of interactions. This will be specially important when we extend the Callback feature as we have planned in the road map.

The idea here is that you can request callbacks with different intentions: support, billing, orders, etc.

The snippet below shows a setting like this:

let supportInteractionVC = InteractionViewController(intention:"support")
callBackViewControllerVC.title = "Support"

let billingInteractionVC = InteractionViewController(intention:"billing")
callBackViewControllerVC.title = "Billing"

let ordersInteractionVC = InteractionViewController(intention:"orders")
callBackViewControllerVC.title = "Orders"

tabBarViewController.viewControllers = [supportInteractionVC, billingInteractionVC, ordersInteractionVC]

This setup needs some extra configurations on Talkdesk. Contact us at mobile-sdk-support@talkdesk.com in order to get help.

Configuring Talkdesk

In order to test the Callback feature you will need to have a configured account with Talkdesk.

If you need to get an account with Talkdesk get in touch with us at mobile-sdk-support@talkdesk.com.

If you already have an account but need to set it up check the Talkdesk’s KnowledgeBase Getting Started section.

If you’re looking how to configure a phone number have a look on Talkdesk’s KnowledgeBase Configure a Phone Number.

If you need to configure the Ring Group associated to your account go to Talkdesk’s KnowledgeBase Setting up Teams: Ring Groups.

You can always get help from us at mobile-sdk-support@talkdesk.com.