Webhooks
This section explains each of the webhooks that can be declared within the Cockpit to improve the user experience and give the user a customized conversation for his needs
To learn more about Syntphony CAI's features that use webhooks:
Basic request and response
The webhooks have the same base request, called conversation event. The information in this event is common for all webhooks, and each one add the information needed for its execution.
Basic request body
Name
Type
Required
Description
text
String
No
User inputted text or transcription from audio.
code
String
No
Code sent by the channel. See conversation service.
info
Info
Yes
Information about the virtual agent, channel and session of the current transaction
entities
Entity[]
No
List of entities returned by the NLP
intents
Intent[]
No
List of intents returned by the NLP
openContext
JSON Object
No
visibleContext
JSON Object
No
hiddenContext
JSON Object
No
Info
Name
Type
Required
Description
bot
String
Yes
Name of the virtual agent
operatingSystem
String
Yes
Same as conversation service
operatingSystem
Version
String
No
Same as conversation service
browser
String
No
Same as conversation service
browserVersion
String
No
Same as conversation service
userRef
String
Yes
Same as conversation service
businessKey
String
No
Same as conversation service
locale
String
Yes
Same as conversation service
channelName
String
Yes
Name of the channel
channelType
String
Yes
Type of the channel (i.e. Web, Whatsapp)
channelClassification
String
Yes
Classification for the types of channel (i.e. Messaging Platform, Smart Assistants)
sessionCode
String
Yes
Same as conversation service
Intent
Name
Type
Required
Description
name
String
Yes
Name of the intent, same as the NLP
confidence
Double
Yes
Confidence score returned by the NLP, this will be a percentage number from 0 to 1.
Entities and intents are read-only attributes. That means you cannot edit their content.
Entity
Name
Type
Required
Description
name
String
Yes
Name of the entity, same as the NLP.
value
String
Yes
The value of the entity returned by the NLP.
position
Position
No
Position of the string within the user input (text).
Entities and intents are read-only attributes. That means you cannot edit their content.
Position
Name
Type
Required
Description
start
Integer
No
Starting position
end
Integer
No
End position
Basic response body
Name
Type
Required
Description
openContext
JSON Object
No
visibleContext
JSON Object
No
hiddenContext
JSON Object
No
Transactional answer
In the Cockpit, when creating an answer, there is an option to mark the answer as “transactional”. If this option is checked, the webhook field appears. Enabling this options means that this answer has dynamic content that must replaced by the webhook.
When this answer is executed by Syntphony CAI, the webhook is called so it can modify the answer before delivering it to the user. This functionality is used to make answers dynamic.
Request body
This service will add the following fields to the basic request body.
Name
Type
Required
Description
answer
AnswerTemplate
Yes
Answer as created through the Cockpit
Answer Template
Name
Type
Required
Description
content
Content
Yes
The content is based on the template selected through the Cockpit
template
String
Yes
Template selected in the Cockpit.
See Answer.type
technicalText
String or JSONObject
No
This field is used for specific behaviours for an answer. It is an open field in the Cockpit. The type depends on how the field is filled in the Cockpit.
.
Content
Name
Type
Required
Description
content
Any
Yes
This content can be a Carousel or a String.
See Answer.content
description
String
No
Same description as created through the Cockpit.
type
String
No
See AnswerTemplate.template
buttons
Button[]
No
See Answer.buttons
quickReply
Button[]
No
See Answer.quickReply
Response body
This service will add the following fields to the basic response body.
Name
Type
Required
Description
answer
AnswerTemplate
Yes
Answer as created through the Cockpit
Sample request
When Syntphony CAI is executing an answer marked as transactional, it will send a request like the one below. In this example, the user said “hi there!” and we want to greet the user back, but replacing the [NAME] string with the user’s name.
Sample response
Continuing the example above, this webhook will call another service to fetch the user info using the id that is stored in the hiddenContext (this data cannot be shared with other systems).
After calling another service, we will load the user data inside the safe context and change the content of the answer.
Service cell
Method:
POST
Type:
application/json
While the Transactional answer is used to dynamically change the content of the answer, the Service cell is used to change the flow of the dialogue. For example, when a user asks for his balance, the virtual agent might have to check if the user is a client before continuing the flow, fetching his balance (giving a transactional answer) if he is a client or asking him if he wants to become one if he is not a client.
In this example the service is called to check if the user is either a CLIENT or NOT_CLIENT.
Request body
This service will add the following fields to the basic request body.
Name
Type
Required
Description
expectedOptions
String[]
Yes
List of options created through the Cockpit. In the example above “CLIENT” and “NOT_CLIENT”.
Response body
This service will add the following fields to the basic response body.
Name
Type
Required
Description
option
String
Yes
Single option to be interpreted by the Dialog Manager and change the dialogue flow.
Sample request
In this example we will check if the user is a client or not using an ID that is present in the context.
Sample response
The example below is telling the Dialog Manager to execute the flow continuing from the CLIENT option.
Last updated
