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}"
    }]
}

Mutation object

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}",
        ...
    }
}

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}",
        ...
    }
}

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"
    }
}

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}"
}

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}

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