Configuring multi-conversations

Multi-conversation functionality allows end users to engage in multiple concurrent conversations with your organization. Currently in messaging, end users are limited to one conversation at a time, making it challenging to address multiple issues simultaneously. With multi-conversations, end users can start new conversations with your organization even if they already have active conversations ongoing.

What you’ll need

• A Zendesk account with a Sunshine Conversations plan. See About Sunshine Conversations platform access.
• A Zendesk admin has configured multi-conversations. See Multiple conversations for end users.
• Zendesk mobile SDK version 2.10.0 and later. We recommend version 2.25.0 and later for an optimal user experience. See iOS 2.10.0, iOS 2.25.0, Android 2.10.0, and Android 2.25.0.

Setting custom titles and avatars for conversations

Zendesk customers with access to the Sunshine Conversations UpdateConversations endpoint can customize multi-conversation titles and avatars. When conversation titles and avatars are updated, the changes are not immediately reflected on the user's current messaging screen. Instead, the updated title or avatar will be displayed the next time the user reloads their messaging screen.

To set the title and avatar for each conversation, use the displayName and iconUrl parameters, respectively. For example:

{
  "displayName": "My conversation",
  "iconUrl": "https://www.someplace.com/image.jpg"
}

If displayName or iconUrl are not specified, the title and the avatar of the conversation defaults to the most recent agent or bot involved in the conversation.

Note: Using the UpdateConversation endpoint requires a Conversations API key which can be generated in the Zendesk Admin Center. See Using the Conversations API keys.

User authentication

If you are using authentication, it's important to authenticate your users with the Zendesk Web Widget or mobile SDKs prior to displaying the messaging screens. Delaying authentication may result in users engaging in anonymous conversations, complicating their ability to access prior conversations and potentially causing them to create new tickets for existing issues (duplicating tickets). For more information, see Enabling authenticated visitors for messaging with Zendesk SDKs.

Authentication in the Zendesk Web Widget

Here is a sample code snippet for authenticating users at the same time as the widget is displayed. For more information, see Displaying the messaging Web Widget.

zE("messenger", "hide")

zE("messenger", "loginUser", function (callback) {
  callback("new-jwt-for-user")
  zE("messenger", "show")
})

Authentication in the Zendesk mobile SDKs

With mobile SDKs, authentication should be completed after the SDK initializes but before presenting the messaging view. For more information, see Authentication in the iOS SDK and Authentication in the Android SDK.

Sample code snippets for Swift

Using async/await API (iOS 13 and later)

Task { @MainActor [weak self] in
    do {
        // Initialize the Zendesk SDK
        _ = try await Zendesk.initialize(withChannelKey: channelKey, messagingFactory: DefaultMessagingFactory())

        // Login user
        _ = try await Zendesk.instance?.loginUser(with: JWT)

        // Presenting the messaging view
        if let messagingViewController = Zendesk.instance?.messaging?.messagingViewController() {
            self?.navigationController?.pushViewController(messagingViewController, animated: true)
        }
    } catch let error {
        // Handle any error
    }
}

Using completion handler (iOS 12 and later)

// Initialize the Zendesk SDK
Zendesk.initialize(withChannelKey: channelKey) { initializationResult in
    switch initializationResult {
    case .success(let zendesk):
        // Login user
        zendesk.loginUser(with: JWT) { loginResult in
            switch loginResult {
            case .success:
                // Presenting the messaging view
                if let messagingViewController = zendesk.messaging?.messagingViewController() {
                    DispatchQueue.main.async { [weak self] in
                        self?.navigationController?.pushViewController(messagingViewController, animated: true)
                    }
                }
            case .failure(let error):
                // Handle login error
                break
            }
        }
    case .failure(let error):
        // Handle initialization error
        break
    }
}

Using Objective C

// Initialize the Zendesk SDK
__weak typeof (self) _weakSelf = self;
[Zendesk initializeWithChannelKey:[self channelKey]
                 messagingFactory:[[ZDKDefaultMessagingFactory alloc] init]
                completionHandler:^(Zendesk *zendesk, NSError *error) {
    if (error != nil) {
        NSLog(@"Initialisation failed with error: %@", error.localizedDescription);
        return;
    }

    // Login user
    Zendesk *instance = [Zendesk instance];
    [instance loginUserWith:@"your_jwt_here" completionHandler:^(ZDKZendeskUser * _Nullable user, NSError * _Nullable error) {
        if (error != nil) {
            NSLog(@"Login failed with error: %@", error.localizedDescription);
            return;
        }
        __strong typeof (self) _strongSelf = _weakSelf;

        // Presenting the messaging view
        UIViewController *viewController = [Zendesk.instance.messaging messagingViewController];
        if (viewController != NULL) {
            [_strongSelf.navigationController showViewController:viewController sender:self];
        }
    }];
}];

Sample code snippets for Android

Using coroutines and suspend functions

val channelKey = "Your channel key"
val jwt = "Your JWT"
coroutineScope.launch {
    val initializationResult = Zendesk.initialize(
        context = context,
        channelKey = channelKey,
        messagingFactory = DefaultMessagingFactory()
    )
    if (initializationResult is ZendeskResult.Success) {
        val loginResult = Zendesk.instance.loginUser(jwt)
        if (loginResult is ZendeskResult.Success) {
            Zendesk.instance.messaging.showMessaging(context)
        } else {
            // Handle login error
        }
    } else {
        // Handle initialization error
    }
}

Using callbacks

val channelKey = "Your channel key"
val jwt = "Your JWT"
Zendesk.initialize(
    context = context,
    channelKey = channelKey,
    successCallback = { zendesk ->
        zendesk.loginUser(jwt = jwt, successCallback = {
            Zendesk.instance.messaging.showMessaging(context)
        }, failureCallback = {
            // Handle login error
        })
    },
    failureCallback = { error ->
        // Handle initialization error
    },
    messagingFactory = DefaultMessagingFactory()
)

Using Java

String channelKey = "Your channel key";
String jwt = "Your JWT";
Zendesk.initialize(
    context,
    channelKey,
    zendesk -> {
        zendesk.loginUser(
            jwt,
            zendeskUser -> {
                zendesk.getMessaging().showMessaging(context);
            },
            throwable -> {
                // handle login error
            }
                );
            },
    error -> {
        // Handle initialization error
    },
    new DefaultMessagingFactory()
);

Limitations

Unity SDK

The Zendesk Unity SDK does not support the multi-conversations feature. If you enable this feature for other native messaging channels (such as the Zendesk Web Widget) and users initiate multiple conversations through those channels, they will only see their most recently updated conversation when they authenticate via the Unity SDK. Other conversations will not be visible in the Unity SDK.

Hiding the conversations list

When an end user starts multiple conversations, they can view them at any time through their conversation list screen, allowing them to revisit or continue past discussions as needed.

The Sunshine Conversations API v2 includes a canUserSeeConversationList property that can hide the conversation list screen and display a single-conversation interface. This setting limits end users to only seeing their latest conversation. Although this feature is available in the Sunshine Conversations API v2, it is not supported in the Zendesk Web Widget or mobile SDKs, meaning users can access all ongoing conversations.

If an end user engages in just one conversation and the system configuration to add more conversations is disabled, they will be sent directly to that conversation screen, skipping the conversation list screen. In this scenario, the conversation list screen is unnecessary and will not be shown.

Sunshine Conversations API v1

Sunshine Conversations API v1 does not support multi-conversations. Enabling the multi-conversations feature while using API v1 may lead to unexpected results.