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:

• Services cell

• Transactional Answers

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	See open context
visibleContext	JSON Object	No	See visible context
hiddenContext	JSON Object	No	See hidden context

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	See open context
visibleContext	JSON Object	No	See visible context
hiddenContext	JSON Object	No	See hidden context

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.

{
   "answer": {
      "content": {
         "content": "Hi, [NAME]. How may I help you?",
         "description": "Dynamic user greeting",
         "type": "TEXT",
         "buttons": [],
         "quickReply": []
      },
      "template": "TEXT"
   },
   "info": {
      "bot": "MyBot",
      "channelName": "MyHomepage",
      "channelType": "Web",
      "channelClassification": "Mobile / Tablet / Desktop",
      "sessionCode": "beaf7d7d-2642-4827-bc51-ecf74ba64dd8",
      "operatingSystem": "Windows",
      "operatingSystemVersion": "10",
      "browser": "",
      "browserVersion": "",
      "userRef": "200.222.134.27",
      "businessKey": "5662988",
      "locale": "en-US"
   },
   "text": "hi there!",
   "openContext": {
      "unsafeVar": 55
   },
   "visibleContext": {
      "unsafeVarRO": "foo"
   },
   "hiddenContext": {
      "id": 6722
   },
   "intents": [
      {
         "name": "HELLO",
         "confidence": 0.987576
      },
      {
         "name": "GOODBYE",
         "confidence": 0.147442
      }
   ],
   "entities": []
}

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.

{
   "answer": {
      "content": {
         "content": "Hi, John. How may I help you?",
         "description": "Dynamic user greeting",
         "type": "TEXT",
         "buttons": [],
         "quickReply": []
      },
      "template": "TEXT"
   },
   "openContext": {
      "unsafeVar": 55
   },
   "visibleContext": {
      "unsafeVarRO": "foo"
   },
   "hiddenContext": {
      "id": 6722,
      "clientInfo": {
         "name": "John Doe",
         "id": 6722,
         "birthdate": "1980-03-03",
         "document": "87237236722"
      }
   }
}

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.

Since the service call can return an error, the SERVICE ERROR is shown

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.

{
   "expectedOptions": [
      "CLIENT",
      "NOT_CLIENT"
   ],
   "info": {
      "bot": "MyBot",
      "channelName": "MyHomepage",
      "channelType": "Web",
      "channelClassification": "Mobile / Tablet / Desktop",
      "sessionCode": "beaf7d7d-2642-4827-bc51-ecf74ba64dd8",
      "operatingSystem": "Windows",
      "operatingSystemVersion": "10",
      "browser": "",
      "browserVersion": "",
      "userRef": "200.222.134.27",
      "businessKey": "5662988",
      "locale": "en-US"
   },
   "text": "hi there!",
   "openContext": {
      "unsafeVar": 55
   },
   "visibleContext": {
      "unsafeVarRO": "foo"
   },
   "hiddenContext": {
      "id": 6722
   },
   "intents": [
      {
         "name": "HELLO",
         "confidence": 0.987576
      },
      {
         "name": "GOODBYE",
         "confidence": 0.147442
      }
   ],
   "entities": []
}

Sample response

The example below is telling the Dialog Manager to execute the flow continuing from the CLIENT option.

{
   "option": "CLIENT",
   "openContext": {
      "unsafeVar": 55
   },
   "visibleContext": {
      "unsafeVarRO": "foo"
   },
   "hiddenContext": {
      "id": 6722,
      "clientInfo": {
         "name": "John Doe",
         "id": 6722,
         "birthdate": "1980-03-03",
         "document": "87237236722"
      }
   }
}