This page offers useful information about webhooks in Chatbot. You will find information about the following topics:
The Inbenta Chatbot can connect to external services to carry out data retrieval operations from your data services and to request the execution of operations into your transactional systems.
The architecture diagram below outlines how Inbenta can establish this communication through the configuration of webhooks (This link opens a third-party website that is not affiliated with Inbenta).
As the diagram shows, there are two different paths to execute a transaction:
To make the handling of transaction by the Inbenta Chatbot Platform easy and flexible, webhooks become an abstraction layer that can connect to any external transactional service. This provides homogeneity in the handshake with the chatbot.
A webhook will consist of a POST HTTPS connection sent to a web application. Form data provides all the parameters that the transactional service behind the webhook requires. The webhook then implements the communication protocol with the transactional service. It collects the output of this service, then maps it into a simple structure that the Inbenta Chatbot uses to process the result of the transaction automatically. This is illustrated by the following flowchart:
The above chart illustrates the flow that the chatbot follows once Inbenta NLU identifies that the user’s intent is to execute a transaction. The “Send Webhook Request” action step bundles together the HTTPS request and the webhook, and collects the webhook's response. If the format of the response is valid, and if the response returns a success state, then the transaction is confirmed to the end user.
The Inbenta Chatbot collects all necessary parameters and bundles them together with the session ID to create the request to the webhook application. It propagates all the parameters in the request's POST form data.
All webhook requests follow this pattern:
https://webhooks.customer.com/flight-details/
[
"inbenta_context": [
"sessionId" => "4aqo58oca8sjr1n4bbcmlvv993"
],
"parameterName1" => "variableValue1"
"parameterName2" => "variableValue2"
"parameterName3" => "variableValue3"
...
]
Webhook requests are not JSON encoded. Data is provided using an HTTP POST form data payload
You can configure parameter names in your Chatbot App from the Knowledge > Action tab (This link opens the Inbenta Help Center. You need an Inbenta account to access it).
Example with Curl:
curl https://webhooks.customer.com/mywebhook -d 'inbenta_context[sessionId]=1234¶meter1=value1
All webhook responses must follow a specific format to allow the Inbenta Chatbot to process the result of the transaction automatically and return custom responses to the end user.
Webhook responses must return a JSON with three main attributes:
1 Important: When the webhook returns a parameter value, the API always tries to capture this value and store it within one of the variables of the instance, under the following rules:
{
"status": "success",
"raw_output": [
{
"output_variable": "parameterName1",
"output_result": "VariableValue1"
},
{
"output_variable": "parameterName2",
"output_result": "VariableValue2"
},
{
"output_variable": "parameterNameN",
"output_result": "VariableValueN"
}
],
"chatbot_response": "Transaction has been completed."
}
The status
and message
fields are mandatory. Optionally, the webhook can include and show a chatbot_response
to give the end user some feedback about the error. The message
field is only used for logging purposes. The end users never see it.
{
"status": "error",
"message": "Internal booking service error"
"chatbot_response": "Sorry, there are no flights available for these dates"
}
Webhook Example
One of your users wants to retrieve their flight information. The Inbenta Chatbot's instruction is to collect the user e-mail address and the reference number provided when the ticket was purchased.
After it successfully collects the required parameters, the Chatbot submits a request to the designated webhook like this:
https://webhooks.customer.com/flight-details/
{
"inbenta_context": {
"sessionId": "4aqo58oca8sjr1n4bbcmlvv993"
},
"e-mail" : "johnny5@novalabs.com"
"reference-number" : "1234"
}
Example in Curl:
curl https://webhooks.customer.com/flight-details/ -d
'inbenta_context[sessionId]=1234&email=johnny5@novalabs.com&transaction_ref=1234'
The chatbot collects the two parameters and fires the request to the Webhook. This triggers a request to execute the transaction to your internal services, and returns the following response:
{
"status": "success",
"chatbot_response": "Your Flight INB1234 will depart at 13h45.",
"raw_output": [
{
"output_variable": "NEXT_FLIGHT_NUMBER",
"output_result": "INB1234"
},
{
"output_variable": "NEXT_FLIGHT_DEPARTURE_TIME",
"output_result": "13h45"
},
{
"output_variable": "UserName",
"output_result": "John Doe"
}
]
}
The user receives the response as it is formatted in the chatbot_response
object. However, the raw_output
object provides relevant raw details that the Inbenta Chatbot can keep in memory if you configure the Webhook accordingly. For example, the two variables UserName
and UserType
might be variables that you want to retain, to avoid having to request them again if the Chatbot needs to carry out more transactions, or because the type of user defined obtains special treatment by the chatbot.
You can follow this transactional link process to securely streamline the handshake with other transactional services through other Webhooks. This simplifies the work of Chatbot managers and allows them to focus on providing the desired customer experience. Webhooks also provide a robust and durable layer that you or your external integration services can fully control. This way, you are not dependent on the Chatbot platform to keep the handshake methods synchronized with updates on your transactional services.
You can use a webhook to capture multiple values:
{
"status": "success",
"raw_output": [
{
"output_variable": "available_car_colors",
"output_result": ["red", "green", "black", "purple"]
}
],
"chatbot_response": "Transaction has been completed."
}
Multiple values can only be captured if all sent values are captured. If one of them is not accepted by the variable restrictions, the variable value does not change. When a variable that allows multiple values does not have any captured values, the related dynamic list variable does not have the source values that it needs to perform value capture and display possible values as selectable options. Inbenta recommends that you add a default value to multiple values variables to avoid obtaining empty variables.
You can also use a webhook to reset a Chatbot variable:
{
"raw_output": [
{
"output_variable": "parameterName1",
"output_result": null
}
]
}
When you reset a variable, the Chatbot will first try to capture its default value. If there is none, the variable value will be cleared.
You can also still use “raw_output” to capture variable values as before. Here is an example of how to reset and then capture different variables in the same webhook:
{
"raw_output": [
{
"output_variable": "parameterName1",
"output_result": null
},
{
"output_variable": "parameterName2",
"output_result": "newValue"
},
{
"output_variable": "parameterName3",
"output_result": "newValue2"
}
]
}
There are two types of timeouts: controlled timeouts and uncontrolled timeouts. A controlled timeout occurs when the webhook’s server itself recognizes the process is taking too long to process a request and breaks the connection. In this case:
When the webhook takes longer than 30 seconds, which is the standard webhook response timeout limit, this is called an uncontrolled timeout. This means that the Chatbot API considers the webhook status to be “failed” after 30 seconds of execution time.
In this case:
Inbenta therefore recommends that you set webhooks to time out sooner to ensure that the Chatbot API can return a message to the user in case of a timeout.
When you use a proxy, the webhook response timeout is reduced to 3 seconds. To use a proxy, you need to enable the “Use Proxy” setting under Settings > General Settings > Webhooks global configuration in your Chatbot instance. For more information, see Webhooks global configuration in the Inbenta Help Center.
The following restrictions apply to webhooks:
The default Amazon API gateway endpoints are not accepted in webhooks. If your webhook has an URL similar to the following:
https://{XXXXX}.execute-api.{REGION}.amazonaws.com{/YYYYY….}
You have to setup a custom domain name using Amazon Route 53, so your webhook URL looks like this:
yourClientDomain.com{/YYYYY....}
See the official Amazon documentation in order to setup custom domain names: Setting up custom domain names for REST APIs - Amazon API Gateway and Routing traffic to an Amazon API Gateway API by using your domain name.