Custom Chatbot

Self-Service Intent Cells have now been updated to support external chatbots in addition to the already supported DialogFlow. This document describes the agent configuration as well as the structure of the outgoing and incoming messages.

Agent Configuration

You can now select a ‘type’ when editing an agent under settings à Dialogflow Agent. By default, the value is set to ‘Dialogflow’. In this case it expects the same Dialogflow configuration that has been provided thus far in setting up these agents.

If you select ‘External’ for the ‘type’ value, then you can use the following structure to setup a remote source to act in place of Dialogflow as the chatbot.

KeyValue TypeDescription
remote_urlStringEndpoint for POST requests from intent cells.
reply_on_responseBooleanWhether the response of the request contains the response message to present to the user.
uses_built_in_promptsBooleanWhether the built-in QContact prompts and re-prompts are being used. If this is false, then all prompts are delegated to the remote chatbot.
query_character_limitIntegerOptional, limit for the length of the user’s message being passed to the remote source. Any characters going over the specified limit are truncated.
Example

Outgoing Message Structure

A POST request will be made to the remote source containing information on the current conversation as well as the context of the request in JSON format.

KeyValue TypeDescription
conversation_idLongID of the conversation.
interaction_idLongID of the self-service interaction.
cell_nameStringThe name of the current cell.
messageStringThe message being pushed. This field can be null, in cases such as the context being a prompt.
contextEnumEnumeration described in the table below.

Possible values of context

ContextDescription
messageA (chat)message being passed to the remote source.
promptIndication that the cell has been entered. This context would only ever get pushed to the remote source if the agent configuration specified to not use the built-in prompts. Example of a built-in prompt would be ‘What can I help you today?’.
repromptIndication that the cell has been re-entered. This context would only ever get pushed to the remote source if the agent configuration specified to not use the built-in prompts. Example of a built-in re-prompt would be ‘Is there anything else I can help with?’.
Example

Incoming Message Structure

The structure of an incoming message will differ slightly depending on whether it comes from the outgoing request’s response or whether a new web request is made from the remote source to send a message in the conversation.

If the remote source sends messages as separate web requests, then ‘reply_on_response’ should be set to ‘false’ in the dialogflow agent configuration. See paragraph ‘Agent Configuration’ for more information regarding the agent configuration.

Note as well that if the remote source uses separate requests to send messages that these requests are QContact authenticated, as other calls to an entity’s action.

The endpoint to use for sending messages as separate web requests is /api/v2/webhooks/chatbot/inbound_message using the POST method. The structure of the message will once again be in JSON. See the table for the structure of the body.

KeyValue TypeDescription
conversation_idLongID of the conversation. This field is only required if a web request originating from the remote source is sending a message to QContact.
interaction_idLongID of the self-service interaction. This field is only required if a web request originating from the remote source is sending a message to QContact.
outputEnumAn enumeration described in the table below.
messageStringThe (chat)message being sent from the remote source.
intent_actionStringAn intent action. This field is only required when responding with KnowledgeBase articles. See the paragraph about KnowledgeBase articles for more information.
OutputDescription
presentA presentation of a message. This is used for sending messages from the remote source.
hangupHanging up the conversation.
intentIndicating that an intent has been triggered and that the self-service cell should follow its output specified in the ‘message’ key of the payload.
errorHanging up the conversation with the built-in system error message.
unknownIndicating that the input is unknown and that the self-service cell should follow its on_invalid_response output.
Possible values of output
Example 1
Example 2
Example 3
Example 4

When the remote source performs web requests to send messages it is possible to encounter the response codes specified below.

StatusDescription
200The message has been received correctly from the remote source.
404The conversation or interaction ID cannot be found in association to the requesting user’s organization.
400The JSON response of the request will specify what is wrong with the request.  

Conversation Ended – The conversation was hung up. Interaction Ended – The interaction was hung up.
Interaction Invalid – The interaction is not a self-service interaction.
Interaction Current Cell Invalid  – The current cell of the interaction is not an external agent configured intent cell. 
Example of a status 400 response

KnowledgeBase Articles

It is possible to still use KnowledgeBase articles for responses like in Dialogflow. See figure 4.4 for an example of the message specifying to present a KnowledgeBase article. The structure of ‘intent_action’ is the entity ID of the KnowledgeBase article prefixed with ‘kb.’. Note that the ‘Chatbot Activity’ report works for external dialogflow agents as well given that the ‘reply_on_response’ is configured to true.