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

Info

Intent

Entities and intents are read-only attributes. That means you cannot edit their content.

Entity

Entities and intents are read-only attributes. That means you cannot edit their content.

Position

Basic response body

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.

Answer Template

Content

Response body

This service will add the following fields to the basic response body.

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

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.

Response body

This service will add the following fields to the basic response body.

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"
      }
   }
}