Routing control
The Conversational Router allows you to adapt a conversation's behaviour at runtime. Described below are the API endpoints that can be for this purpose.
When calling our APIs we require an authentication token to be present. Please refer to our authentication page for details.
Endpoints
Mutation
A ruleset, as defined in the graphical user interface of the Conversational Router, can be changed at runtime for a specific chat. For this purpose we allow enabling and disabling links between the defined adapters.
POST
to https://api.conversational.cm.com/conversational/control/v1/accounts/{TechnicalLinkId}/chats/{ChatId}/routing/mutationrequests
{
"ChatId": "{ChatId}",
"Mutations": [{
"$type": "ruleMutation",
"action": "{action}",
"operator": "{operator}",
"sourceAdapterId": "{sourceAdapterId}",
"targetAdapterId": "{targetAdapterId}"
}]
}
Field | Description | Required |
---|---|---|
TechnicalLinkId | The id of the CONVERSATIONAL technical link | Yes |
ChatId | A hash created from the combination of client id, host id and channel | Yes |
Mutations | A list of Mutation objects | Yes |
Context | An object containing context-giving key-value pairs, used for skill-based routing | No |
Mutation object
Field | Description | Required |
---|---|---|
$type | The type of mutation, at this point in time always ruleMutation | Yes |
action | The type of action, Enable or Disable | Yes |
operator | Whether the link(s) to be mutated should be connected to the source adapter and target adapter or either one of those, And or Or | Yes |
sourceAdapterId | The id of the adapter where the to be mutated link(s) originate | No |
targetAdapterId | The id of the adapter where the to be mutated link(s) destinate | No |
Skill-based routing
When handing over a conversation from a bot (Scripted Chatbot, Conversational AI Cloud) to customer contact software (Mobile Service Cloud) 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 mutation.
{
"ChatId": "{ChatId}",
"Mutations": [{
"$type": "ruleMutation",
"action": "{action}",
"operator": "{operator}",
"sourceAdapterId": "{sourceAdapterId}",
"targetAdapterId": "{targetAdapterId}"
}],
"Context": {
"{key1}": "{value1}",
...
}
}
Command
Commands are groups of preconfigured mutation requests that are capable of disabling or enabling specific components. In this way the setup of a conversation can be changed. For example, a customer talking to a bot can get a "handover" to an agent in case the bot is not able to handle the situation appropriately.
The pre-configuration is done within the graphical user interface of the Conversational Router.
POST
to https://api.conversational.cm.com/conversational/control/v1/accounts/{TechnicalLinkId}/chats/{ChatId}/commands
{
"Name": "{Name}",
"Origin": "{Origin}",
"Context": {
"{key1}": "{value1}",
...
}
}
Field | Description | Required |
---|---|---|
TechnicalLinkId | The id of the CONVERSATIONAL technical link | Yes |
ChatId | A hash created from the combination of client id, host id and channel | Yes |
Name | The name of the command that is configured in the Conversational Router | Yes |
Origin | The origin of the command request; this is used in analytics (please provide the name of your app or company in this field) | Yes |
Context | An object containing context-giving key-value pairs, used for skill-based routing | No |
Position
Move execution of a Scripted Chatbot script to the specified step.
POST
to https://api.conversational.cm.com/conversational/control/v1/accounts/{TechnicalLinkId}/sessions/positionrequests
{
"ChatId": "{ChatId}",
"FlowId": "{FlowId}",
"StepId": "{StepId}",
"Context": {
"{key1}": "{value1}",
...
}
}
Field | Description | Required |
---|---|---|
TechnicalLinkId | The id of the CONVERSATIONAL technical link | Yes |
ChatId | A hash created from the combination of client id, host id and channel | Yes |
FlowId | The id of a flow in the Scripted Chatbot script | Yes |
StepId | The id of a step in the Scripted Chatbot script | Yes |
Context | Context can be used to override session variables already defined in script | No |
The FlowId and StepId need to be retrieved from the Scripted Chatbot builder.
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.
POST
to https://api.conversational.cm.com/conversational/control/v1/accounts/{TechnicalLinkId}/chats/{ChatId}/routing/reset
{
"Reason": "Conversation ended",
"Context": {
"key1": "value1",
"key2": "value2"
}
}
Field | Description | Required |
---|---|---|
TechnicalLinkId | The id of the CONVERSATIONAL technical link | Yes |
ChatId | A hash created from the combination of client id, host id and channel | 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.
Note: this endpoint requires the X-Cm-Producttoken
header to be present.
POST
to https://api.conversational.cm.com/conversational/control/v1/accounts/{TechnicalLinkId}/routing/ensure-new-session
{
"ClientId":"{ClientId}",
"HostId":"{HostId}",
"Channel":"{Channel}"
}
Field | Description | Required |
---|---|---|
TechnicalLinkId | The id of the CONVERSATIONAL technical link | 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).
Chat id construction
Construct the chat id belonging to the combination of client, host and channel.
Note: this endpoint requires the X-Cm-Producttoken
header to be present.
GET
to https://api.conversational.cm.com/conversational/control/v1/accounts/{TechnicalLinkId}/chatId?channel={Channel}&clientId={ClientId}&hostId={HostId}
Field | Description | Required |
---|---|---|
TechnicalLinkId | The id of the CONVERSATIONAL technical link | 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).
Updated 2 months ago