Skip to main content

Concepts

Chat vs session​

Understanding the difference between a chat and a session is essential.

  • Chat: a chat refers to the communication between both end-user to end-user and end-user to automated system (even automated system to automated system) on a single messaging channel. It is a long-lived thread that connects the same participants on the same channel.
  • Session: a session, on the other hand, is a single, finite interaction within that chat. Essentially, a single chat can contain multiple sessions.

For more detailed information, visit the Chat ID construction page.

Chat ID​

The chat ID is a key concept to understand, as it uniquely identifies a chat and is used throughout this documentation. It is constructed using three components: channel, client ID and host ID. For more details on these components, refer to the Chat ID construction page.

📘 Chat ID reversibility

The chat ID is not reversible, meaning you cannot extract the channel, client, or host IDs from it. However, this is not necessary, as these fields are included in the payload sent via TwoWay.

Additionally, there is an API available for constructing chat IDs — see the Chat ID construction page.

Router components​

The key components of the Router are channels, applications, flows and states.

Channels​

Channels are the entry points of the Router: the messaging channels your customers use to reach you. They are managed on the Channels page. CM's communication channels are provided by Business Messaging; a custom service can act as a channel through the TwoWay API.

Applications​

Applications are the destinations of the Router: ready-made connections such as a bot or an agent inbox that handle routed conversations. They are managed on the Applications page; see Connections for the catalog.

Flows​

A flow defines how messages are routed through the Conversational Router for a given use case (see the Flows page).

States​

A state is a distinct phase within a flow that determines how messages are routed at a given moment (see the States page).

APIs

We have several APIs that can be used for custom integrations:

  • TwoWay API. TwoWay is a JSON-based format the Conversational Router uses to exchange data with external services. Use the TwoWay API to connect your service to the Conversational Router. Read more about it on the TwoWay API page.
  • Conversation history API. Conversation History lets you retrieve the full record of a single session, enabling you to review past messages, support workflows, or run analytics. Find more information on the Conversation History API page.
  • Routing control API. This API allows you to modify a conversation's behavior at runtime. For more details see the Routing control API page.
  • Configuration API. This API lets you retrieve the configurations you have set up for the Router. Learn more on the Configuration APIs page.

Authentication

All Conversational Router API requests require authentication to ensure data security and prevent misuse. Authentication involves product token: a credential used to authenticate API requests, included in the X-CM-PRODUCTTOKEN header (e.g., X-CM-PRODUCTTOKEN: {your_product_token}). You can retrieve it in the Router: open the Explorer and click API access to view your product token together with a ready-made example request. When configuring a custom service, the same credentials are shown on the connection's Implementation tab.

❗️ Product token security

It is crucial to keep product tokens secure, as they grant permissions associated with your account. Do not share them with anyone to prevent unauthorized access.

Channels

The CM.com messaging platform supports a wide variety of channels. You can find a list of supported channels and a compatibility matrix on the Channels page under Custom integration.

To route messages through the Business Messaging application, you first need to configure channels in the Channels platform. For each channel identifier, select Router as the message destination. For more details, refer to the Prerequisites section on the Business Messaging page.

Onboarding

When using the Router for the first time, you can take advantage of the onboarding wizard to quickly set up connections and flows. The wizard simplifies the initial configuration process, allowing you to get started with minimal effort. For detailed instructions and additional information, refer to the Onboarding page.

Whitelisting

If applicable, please configure the router source IP 34.34.64.134 in your whitelist so we can deliver your messages.