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}"
    }]
}
FieldDescriptionRequired
TechnicalLinkIdThe id of the CONVERSATIONAL technical linkYes
ChatIdA hash created from the combination of client id, host id and channelYes
MutationsA list of Mutation objectsYes
ContextAn object containing context-giving key-value pairs, used for skill-based routingNo

Mutation object

FieldDescriptionRequired
$typeThe type of mutation, at this point in time always ruleMutationYes
actionThe type of action, Enable or DisableYes
operatorWhether the link(s) to be mutated should be connected to the source adapter and target adapter or either one of those, And or OrYes
sourceAdapterIdThe id of the adapter where the to be mutated link(s) originateNo
sourceAdapterIdThe id of the adapter where the to be mutated link(s) destinateNo

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 as well as perform handovers and takeovers. 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}",
        ...
    }
}
FieldDescriptionRequired
TechnicalLinkIdThe id of the CONVERSATIONAL technical linkYes
ChatIdA hash created from the combination of client id, host id and channelYes
NameThe name of the command that is configured in the Conversational RouterYes
OriginThe origin of the command request; this is used in analytics (please provide the name of your app or company in this field)Yes
ContextAn object containing context-giving key-value pairs, used for skill-based routingNo

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}",
        ...
    }
}
FieldDescriptionRequired
TechnicalLinkIdThe id of the CONVERSATIONAL technical linkYes
ChatIdA hash created from the combination of client id, host id and channelYes
FlowIdThe id of a flow in the Scripted Chatbot scriptYes
StepIdThe id of a step in the Scripted Chatbot scriptYes
ContextContext can be used to override session variables already defined in scriptNo

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"
    }
}
FieldDescriptionRequired
TechnicalLinkIdThe id of the CONVERSATIONAL technical linkYes
ChatIdA hash created from the combination of client id, host id and channelYes
ReasonThe reason for resetting the routerNo
ContextExtra information potentially interesting to parties listening on router resetNo

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}"
}
FieldDescriptionRequired
TechnicalLinkIdThe id of the CONVERSATIONAL technical linkYes
ChannelThe channel over which messages are sentYes
ClientIdThe client id from which messages are sentYes
HostIdThe host id to which messages are sentYes

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}

FieldDescriptionRequired
TechnicalLinkIdThe id of the CONVERSATIONAL technical linkYes
ChannelThe channel over which messages are sentYes
ClientIdThe client id from which messages are sentYes
HostIdThe host id to which messages are sentYes

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).