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.

Messaging screen

The MessagingScreen enum 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.

Show most recent conversation

showMostRecentConversation displays the most recent active conversation. Developers can specify an exitAction to determine the behavior when the user exits this screen.

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

Parameters:

Name	Type	Mandatory	Comment
exitAction	ExitAction	Yes	The action to perform when exiting this screen.

Code example:

Zendesk.instance?.messaging?.messagingViewController(
    .showMostRecentConversation(exitAction: .close)
)

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

showConversationsList

This screen displays the list of all conversations.

Code example:

Zendesk.instance?.messaging?.messagingViewController(
    .showConversationList
)

showConversation

This screen displays a specific conversation identified by its unique id. Developers can specify an exitAction 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. If the conversation id is not informed a new conversation is created.

Parameters:

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

Code example:

Zendesk.instance?.messaging?.messagingViewController(
    .showConversation(
        conversationId: "conversation_id",
        exitAction: .returnToConversationList
    )
)

showNewConversation

This screen allows users to start a new conversation. Developers can specify an exitAction 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
exitAction	ExitAction	Yes	The action to perform when exiting this screen.

Code example:

Zendesk.instance?.messaging?.messagingViewController(
    .showNewConversation(exitAction: .close)
)

Exit action

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
let exitAction = ExitAction.close

FAQ

Q: How to enable multi-conversations in 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: Is it possible to customize the exitAction behavior for each screen? Yes, the exitAction 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.showConversation 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 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: What happens if the specified conversation id is not provided or it is nil? If the specified conversation id is not informed or it is nil, a new conversation is created.

Q: Can misusing the showNewConversation API cause issues? Yes, misusing the showNewConversation API, such as calling it every time the end user clicks to open the conversation, 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 showMostRecentActiveConversation? If no conversations exist, the screen will automatically create a new conversation.

Q: What happens if none of the described APIs is chosen? If you choose not to use the described APIs, the navigation will default to the showMostRecentActiveConversation screen.