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.
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.
|remote_url||String||Endpoint for POST requests from intent cells.|
|reply_on_response||Boolean||Whether the response of the request contains the response message to present to the user.|
|uses_built_in_prompts||Boolean||Whether 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_limit||Integer||Optional, limit for the length of the user’s message being passed to the remote source. Any characters going over the specified limit are truncated.|
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.
|conversation_id||Long||ID of the conversation.|
|interaction_id||Long||ID of the self-service interaction.|
|cell_name||String||The name of the current cell.|
|message||String||The message being pushed. This field can be null, in cases such as the context being a prompt.|
|context||Enum||Enumeration described in the table below.|
Possible values of context
|message||A (chat)message being passed to the remote source.|
|prompt||Indication 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?’.|
|reprompt||Indication 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?’.|
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.
|conversation_id||Long||ID of the conversation. This field is only required if a web request originating from the remote source is sending a message to QContact.|
|interaction_id||Long||ID 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.|
|output||Enum||An enumeration described in the table below.|
|message||String||The (chat)message being sent from the remote source.|
|intent_action||String||An intent action. This field is only required when responding with KnowledgeBase articles. See the paragraph about KnowledgeBase articles for more information.|
|present||A presentation of a message. This is used for sending messages from the remote source.|
|hangup||Hanging up the conversation.|
|intent||Indicating that an intent has been triggered and that the self-service cell should follow its output specified in the ‘message’ key of the payload.|
|error||Hanging up the conversation with the built-in system error message.|
|unknown||Indicating that the input is unknown and that the self-service cell should follow its on_invalid_response output.|
When the remote source performs web requests to send messages it is possible to encounter the response codes specified below.
|200||The message has been received correctly from the remote source.|
|404||The conversation or interaction ID cannot be found in association to the requesting user’s organization.|
|400||The 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.
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.