Multi-conversations navigation APIs

Multi-conversations allow users to seamlessly navigate between multiple conversations within the Zendesk Messaging interface. This feature enhances user experience by providing flexibility in managing conversations. For more details on enabling and configuring multi conversations, refer to the Configuring multi-conversations documentation and Allowing multiple conversations for your users.

Important: Multi-conversations must be enabled in your Zendesk configuration to use the APIs described below. Ensure that this feature is properly set up before integrating these APIs.

MessagingScreen API

The MessagingScreen sealed class represents the different screens available within the Zendesk messaging interface. These screens allow developers to control the navigation and behavior of the messaging UI. Below are the available screens and their usage:

Important: Ensure that the Zendesk instance is initialized before using any of the APIs described in this document. Failure to do so may result in unexpected behavior or errors.

MostRecentActiveConversation

This screen displays the most recent active conversation. Developers can specify an onExit action to determine the behavior when the user exits this screen.

If no conversations exist, the screen automatically creates a default conversation (i.e., a new conversation).

Parameters:

Name	Type	Mandatory	Comment
onExit	ExitAction	No	The action to perform when exiting this screen. Defaults to ExitAction.ReturnToConversationList.

Code example:

Zendesk.instance.messaging.showMessaging(
    context = context, 
    messagingScreen = MessagingScreen.MostRecentActiveConversation(
     onExit = MessagingScreen.ExitAction.ReturnToConversationList
   )
)

If you choose not to use the APIs described below, the default behavior will be MostRecentActiveConversation.

ConversationsList

This screen displays the list of all conversations.

Code example:

Zendesk.instance.messaging.showMessaging(
    context = context, 
    messagingScreen = MessagingScreen.ConversationsList
)

Conversation

This screen displays a specific conversation identified by its unique id. Developers can specify an onExit action to determine the behavior when the user exits this screen.

If the specified conversation ID cannot be found, the screen will default to displaying the conversation list.

Parameters:

Name	Type	Mandatory	Comment
id	String	Yes	The unique identifier of the conversation to display.
onExit	ExitAction	No	The action to perform when exiting this screen. Defaults to ExitAction.ReturnToConversationList.

Code example:

Zendesk.instance.messaging.showMessaging(
    context = context, 
    messagingScreen = MessagingScreen.Conversation(
        id = "conversation_id",
        onExit = MessagingScreen.ExitAction.ReturnToConversationList
    )
)

NewConversation

This screen allows users to start a new conversation. Developers can specify an onExit action to determine the behavior when the user exits this screen.

Important: Misusing this API can result in the creation of multiple new conversations unintentionally. Ensure proper implementation to avoid this issue.

Parameters:

Name	Type	Mandatory	Comment
onExit	ExitAction	No	The action to perform when exiting this screen. Defaults to ExitAction.ReturnToConversationList.

Code example:

Zendesk.instance.messaging.showMessaging(
    context = context, 
    messagingScreen = MessagingScreen.NewConversation(
        onExit = MessagingScreen.ExitAction.ReturnToConversationList
    )
)

ExitAction enum

The ExitAction enum defines the possible actions to take when exiting a messaging screen. The available actions are:

• Close: Closes the screen when done.
• ReturnToConversationList: Navigates back to the conversation list.

Code Example:

// Example usage of ExitAction
val exitAction = MessagingScreen.ExitAction.Close

Demo Apps

To see the new multi-conversations navigation APIs in action, explore the demo apps provided by Zendesk. These apps showcase practical implementations of the APIs and can help you understand how to integrate them into your own projects.

• Zendesk SDK Demo Apps for Android

FAQ

Q: How do I enable multi-conversations in my Zendesk configuration? To enable multi-conversations, refer to the Configuring multi-conversations documentation and Allowing multiple conversations for your users. Ensure that the feature is properly set up before integrating the APIs.

Q: What happens if multi-conversations are not enabled? If multi-conversations are not enabled, the APIs described in this document will not function as expected. Ensure that the feature is enabled in your Zendesk Messaging configuration.

Q: Can I customize the onExit behavior for each screen? Yes, the onExit parameter allows you to define custom behavior when exiting a screen. For example, you can use ExitAction.Close to close the screen or ExitAction.ReturnToConversationList to navigate back to the conversation list.

Q: Is it possible to navigate directly to a specific conversation? Yes, you can use the MessagingScreen.Conversation screen and provide the unique id of the conversation you want to display. Refer to the Conversation screen section for more details and code examples.

Q: What is the default behavior for onExit if not specified? If the onExit parameter is not specified, the default behavior is ExitAction.ReturnToConversationList.

Q: What happens if the specified conversation ID cannot be found? If the specified conversation ID cannot be found, the screen will default to displaying the conversation list.

Q: Can misusing the NewConversation API cause issues? Yes, misusing the NewConversation API can result in the creation of multiple new conversations unintentionally. Ensure proper implementation to avoid this issue.

Q: What happens if no conversations exist when using MostRecentActiveConversation? If no conversations exist, the screen will automatically create a new conversation.

Q: What happens if I choose not to use the described APIs? If you choose not to use the described APIs, the navigation will default to the MostRecentActiveConversation screen.