Skip to main content

Overview

When building custom integrations, Chat ID appears frequently, so it’s important to understand what it represents. Chat ID is the stable identifier for a chat between one end user and one service identity on a single messaging channel. It represents the long‑lived thread linking the same participants on the same channel across time. This differs from routerSessionId, which identifies a single, finite interaction within that chat (for example, one support session that starts and ends). A single chat ID can span multiple routerSessionIds and is useful for grouping conversations historically and operationally.

Concept and composition

What defines a chat​

A chat is defined by the trio of channel, client, and host. The channel is the specific channel over which messages are exchanged. The client is the end user’s identifier on that channel (the client id), and the host is the service identity the user is talking to on that channel (the host id).

Inputs and rationale​

Chat ID is derived from these three inputs: channel, client id, and host id. Including the channel is essential because the same user–service pair can exist across different channels; for instance, the same two phone numbers can converse via SMS and via WhatsApp, and those must be treated as distinct chats. Client and host identifiers always follow the addressing scheme of the channel you are using - for example, 1645 phone number for WhatsApp and SMS or an Instagram Scoped User ID (IGSID) for Instagram.

Uniqueness and scope​

Chat ID is deterministic and unique for the combination of channel, client id, and host id. The same inputs always produce the same identifier, making chat ID a reliable key to group messages and sessions for the same participants on the same channel. Router account ID is not part of this calculation; in the rare case that two accounts share the same host identity on the same channel, the chat ID will be the same across those accounts. If any of the three inputs change - such as migrating to a new host number - a new chat ID is produced and will not automatically link back to the previous one.

Relationship to router session ID​

Use chat ID to group sessions and retrieve history across time for the same participants on the same channel, while routerSessionId identifies a single finite session. You will receive both identifiers in the payloads TwoWay sends. Chat ID can be used for long‑term grouping and analytics, routerSessionId for session‑specific actions and history queries.

Obtaining chat ID​

You will receive chat ID in platform payloads whenever you interact with the Router. This is the preferred way to use it because it ensures consistency across systems and avoids local differences in identifier formatting. If you need the platform to compute the identifier for a given combination of channel, client id, and host id call this control API endpoint.