Overview

The Router allows you to adapt a conversation's behavior at runtime. Described below are the API endpoints that can be used for this purpose.

When calling our APIs we require an authentication token to be present. Please refer to our authentication page for details.

Endpoints

Chat ID construction

Construct the chat ID belonging to the combination of client, host and channel. For more information, see Chat ID construction.

Endpoint: GET https:api.cm.com/router/control/v1/accounts/{LogicalAccountId}/chatId?channel={Channel}&clientId={ClientId}&hostId={HostId}

Header: X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000

Permissions: ConversationalRouter.Chat_Id_Read

Field	Description	Required
LogicalAccountId	The ID of logical account	Yes
Channel	The channel over which messages are sent	Yes
ClientId	The client id from which messages are sent	Yes
HostId	The host id to which messages are sent	Yes

The client and host ID correspond to the identifiers of the channel that is used. E.g. for WhatsApp that's the phone number, for Instagram it is the Instagram Scoped User ID (IGSID).

State change

States, as defined in the graphical user interface of the Router, can be changed at runtime for a specific chat. This functionality allows users to set a new active state from the predefined states.

Endpoint: PUT https://api.cm.com/router/control/v1/accounts/{LogicalAccountId}/chats/{ChatId}/session/state

Header: X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000

Permissions: ConversationalRouter.RouterSession_Update

Request body:

{
    "NewStateNameId": "{stateNameId}",
    "Context": 
      { 
        "{key1}": "{value1}",
				...
      }
}

Field	Description	Required
LogicalAccountId	The ID of logical account	Yes
ChatId	A hash created from the combination of client id, host id and channel. For more information, see Chat ID construction	Yes
NewStateNameId	The ID of the state that needs to be set as active	Yes
Context	An object containing context-giving key-value pairs	No

Skill-based routing

When handing over a conversation from a bot to a live agent, it often is beneficial to be able to route to a specific person or group of persons. This can be achieved by adding context to a state change.

Get router state

Retrieve the current router session state for a specific chat within a given logical account.

Endpoint: GET https://api.cm.com/router/control/v1/accounts/{LogicalAccountId}/chats/{ChatId}/session

Header: X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000

Permissions: ConversationalRouter.RouterChatStates_Read

Field	Description	Required
LogicalAccountId	The ID of logical account	Yes
ChatId	A hash created from the combination of client id, host id and channel. For more information, see Chat ID construction	Yes

Routing reset

Reset the rulesets used to their defaults, as defined in the web application, reverting any mutations that have been applied via the API.

Endpoint: PUT https://api.cm.com/router/control/v1/accounts/{LogicalAccountId}/chats/{ChatId}/session/end

Header: X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000

Permissions: ConversationalRouter.RouterSession_Update

Request body:

{
    "Reason": "{Reason}",
    "Context": {
        "{key1}": "{value1}",
        ...
    }
}

Field	Description	Required
LogicalAccountId	The ID of logical account	Yes
ChatId	A hash created from the combination of client id, host id and channel. For more information, see Chat ID construction	Yes
Reason	The reason for resetting the router	No
Context	Extra information potentially interesting to parties listening on router reset	No

Ensure new session

End active session (if present) and start a new session. The id of the newly started session is returned.

Endpoint: POST https://api.cm.com/control/v1/accounts/{LogicalAccountId}/session/new

Header: X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000

Permissions: ConversationalRouter.RouterSession_Update

Request body:

{
  "ClientId":"{ClientId}",
  "HostId":"{HostId}",
  "Channel":"{Channel}",
  "Reason":"{Reason}",
  "Context":[
    {
      "{key1}":"{value1}"
		}
	],
  "SourceApplicationId":"{SourceApplicationId}"
}

Field	Description	Required
LogicalAccountId	The ID of logical account	Yes
ChatId	A hash created from the combination of client id, host id and channel. For more information, see Chat ID construction	Yes
Channel	The channel over which messages are sent	Yes
ClientId	The client id from which messages are sent	Yes
HostId	The host id to which messages are sent	Yes
SourceApplicationId	The ID of source application	Yes
Reason		No
Context		No

The client and host IDs correspond to the identifiers of the channel that is used. E.g. for WhatsApp that's the phone number, for Instagram it is the Instagram Scoped User ID (IGSID).

Ensure session

Ensure that a routing session exists for the given client, host, and channel. If no session exists, it is created; if it exists, a current session ID is returned.

Endpoint: POST https://api.cm.com/router/control/v1/accounts/{LogicalAccountId}/routing/ensure-session

Header: X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000

Permissions: ConversationalRouter.RouterSession_Update

Request body:

{
    "ClientId":"{ClientId}",
    "HostId":"{HostId}",
    "Channel":"{Channel}"
}

Field	Description	Required
LogicalAccountId	The ID of logical account	Yes
Channel	The channel over which messages are sent	Yes
ClientId	The client id from which messages are sent	Yes
HostId	The host id to which messages are sent	Yes

The client and host IDs correspond to the identifiers of the channel that is used. E.g. for WhatsApp that's the phone number, for Instagram it is the Instagram Scoped User ID (IGSID).

Create outbound session

Creates a session for outbound initiated messages (outreach) using (for example) WhatsApp templates. Changes to the appropriate outbound state if necessary. This API provides information like the applicationId you'll need to send messages to our TwoWay API. Currently useful for Agent Inbox. Get in touch with us for custom integrations.

Endpoint: POST https://api.cm.com/router/control/v1/accounts/{LogicalAccountId}/outbound-session

Header: X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000

Permissions: ConversationalRouter.RouterSession_Update

Request body:

{
  "SourceComponent": "AgentInbox",
  "Channel": "{{Channel}}",
  "ConversationHostId": "{{ConversationHostId}}",
  "ConversationClientId": "{{ConversationClientId}}",
  "ForceNewSession": false
}

Field	Description	Required
SourceComponent	The source component to look up for message routing	Yes
Channel	The channel over which messages are sent	Yes
ConversationHostId	The client id from which messages are sent	Yes
ConversationClientId	The host id to which messages are sent	Yes
ForceNewSession	When true, ends any existing session and starts a new one. Defaults to false	No

Response body:

{
	"SourceApplicationId": "SomeApplicationId",
  "ChatId": "{{ChatId}}",
  "SessionId": "{{SessionId}}",
  "StateId": "{{StateId}}"
}

Field	Description
SourceApplicationId	Application ID to use when sending your outbound message to TwoWay
ChatId	A hash created from the combination of client id, host id and channel. For more information, see Chat ID construction
SessionId	The ID generated for your new session
StateId	ID of the state which is configured to receive the message

Endpoints

Chat ID construction​

State change​

Skill-based routing​

Get router state​

Routing reset​

Ensure new session​

Ensure session​

Create outbound session​

Chat ID construction

State change

Skill-based routing

Get router state

Routing reset

Ensure new session

Ensure session

Create outbound session