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 eva'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 eva, 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 eva 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"
      }
   }
}

Last updated