Creating channels – The Conversation API

What is the Conversation API

Any developer can integrate their own channels to eva. A user could benefit from a chat in the company’s website using a custom interface or even custom templates for responses, such as graphs, masked inputs or interaction with other elements of the webpage.

Companies normally add virtual agent platforms to their existing app, or use one of the internal channels to release a virtual agent for its employees. When using eva, this can be done by consuming the Conversation API described below.

Conversation service

The conversation service is used to execute a conversation. Each call to this service is a message from the user that the virtual agent must process in order to understand and answer the user.

URL Parameters

Request headers

Request body

Response body

User Input

Answer

Button

Carousel card

Sample requests

The request below is an example of a first call to the conversation service, requesting the execution of the welcome flow. It also add a variable to the context, although it is not necessary.

{
	"code": "%EVA_WELCOME_MSG",
	"context": {
		"user": 25237
	}
}

Another possible request, for following user messages:

{
	"text": "How much do I have in my account?",
	"context":{
		"user": 25237,
		"foo": "bar"
	}
}

Sample response

The following JSON is an example for a response for the request above.

{
   "text": "How much do I have in my account?",
   "sessionCode": "555c03b6-d22f-431d-b82e-2b33aff5719d",
   "intent": "BALANCE",
   "confidence": 0.88,
   "answers": [
      {
         "quickReply": [],
         "interactionId": "2f300826-629f-495c-b925-3d6131946934",
         "buttons": [],
         "description": "",
         "type": "TEXT_OPTIONS",
         "content": "You have 10 points in your wallet."
      }
   ],
   "context": {
      "user": 25237,
      "foo": "bar"
   }
}

Loading answers

When you want to avoid NLP calls, eva offers a front-end pre- processing option that bypasses cognitive processing. The CODE practice ties a specific code to a specific answer and obliges eva to deliver this answer.

In eva, a call to the Conversation API with “code”:“%EVA_WELCOME_MSG” loads the welcome flow. When this code appears, eva is obliged to load the welcome flow. The extension of this behavior to any other answer is what is called the CODE practice.

When you register an answer name, it will also be its “code”, eva will deliver that specific answer when faced with that code. If the answer is transactional, the transaction is done before the answer is delivered. If the answer is not found, the “code” content is sent to the NLP so it can be interpreted.

When eva API encounters a “code” and a “text”, the code is and the text not (unless the text is used by a transactional component). If an answer with the same name of the “code” content is not found, the “text” content is sent to the NLP. This happens too in the middle of a flow. If a code is sent in the middle of a flow, the flow is stopped to run the code.

So, eva loading priority will be code --> answer -> NLP --> Fallback.

Every code interaction is registered in the User Interactions table.

This is useful when you want to build a clickable menu with preset options and each option is a code. For example, a simple menu with options such as “check balance”, “check opening times” and “ask for a refund”.

Likable service

The likable service is used when an answer is configured to be evaluable. When this option is enable, the answer should give the user a thumps up / thumbs down option (like / dislike) in the chat.

When the user likes or dislikes an answer, this service must be called.

Request body

Response body

The likable service will return a HTTP Status 200 with a “Success” string.

Sample request

{
   "evaluation": true,
   "interactionId": "7cf85a1e-244b-4c75-bc8d-bb188911c724"
}

Sample Response

"Success"

URL parameters

Request headers

Request body

Response body

The satisfaction service will return a HTTP Status 200 with a “Success” string.

Sample request

{
 "evaluation": 5, 
 "answered": "true",
 "userComments": "You answered where to find the information, but why didn’t you give the info in the chat?",
 "expireSession": true
}

Sample response

"Success"

Integrating Existing Channels

How to integrate other messaging platforms and smart assistants, such as Facebook Messenger, Whatsapp and Google Assistant

Besides custom developed front-ends, such as web chats, mobile chats and IVR, eva can integrate with other messaging platforms and smart assistants, such as Facebook Messenger. This connection asks for a connector between eva and the channel, translating the Conversation API to the form of communication used in the channel.

Some of these connectors exists out-of-the-box in eva and are explained below.

Infobip Whatsapp connector

To configure an Infobip integration, the first step is to add some configuration parameters through the Cockpit. Access the Settings screen and go to the Parameters section.

Add the following parameters:

1. whatsapp.broker.info – this parameter contains the Conversation API configuration for the connector.

The value must be a JSON with these attributes:

Example:

{   "baseUrl": "Erro! A referência de hiperlink não é válida.",   "apiKey": "01a86ff7-e7eb-4482-82ef-d5a3cd120b19",   "project": "MYBOT",   "channel": "WhatsApp Help Desk",   "os": "Infobip connector",   "locale": "es-ES"}

2. whatsapp.infobip.info – this parameter configures the Infobip end of the integration. It is also a JSON value.

Example:

{   "omniUrl": "https://h38h8.api.infobip.com/omni/1",   "user": "MyUser",   "password": "Password1234",   "whatsappNumber": "447494163530",   "channel": "WHATSAPP"}

The last step for this configuration is to go to the Infobip portal, in the number configuration, paste your Infobip Connector URL in the URL field as shown in the image below:

Important:

• The Infobip Connector URL is provided by your eva installation administrator.

Google Assistant connector

This section shows how to integrate with Google Assistant, which can be used in Google Home as well.

1. Create your project in Google Actions

2. Action invocation

Give your action a name for users to use it. For example, if your action’s name is “eva car”, the user will use it by saying “ok google, open eva car”.

It is recommended to put simple words and test the pronunciation.

3. Configuring the action

Download and install the Google CLI and execute the following command.

$gactions init

Doing this, a file named action.json will be generated. Open this file and change the conversation name, name and URL.

{  "actions": [    {       "description": "Default Welcome Intent",       "name": "MAIN",       "fulfillment": {         "conversationName": "<INSERT YOUR CONVERSATION NAME HERE>"       },       "intent": {         "name": "actions.intent.MAIN",         "trigger": {          "queryPatterns": [            "talk to <INSERT YOUR NAME HERE>"          ]        }      }    }  },  "conversations": {    "<INSERT YOUR CONVERSATION NAME HERE>"     "name": "<INSERT YOUR CONVERSATION NAME HERE>"     "url": "<INSERT YOUR CONVERSATION NAME HERE>"   } }, "locale": "en"}

The conversation name and the name are based on your action.

The URL is made of two parts:

The endpoint – this part is provided by your eva installation administrator and will end in /conversations.

Channel ID – the last part will be the ID of the channel that is to be used by Google Assistant.

Your URL should look like this: https://ga-mydemo-eva.bot/conversations/53​

4. Update your action

Go to the Settings tab and copy the Project ID. This information is needed to update the action with the JSON file altered in the previous step.

Update the project with the command below.

$gactions update --action_package action.json --project <Project ID>

This command will provide a URL for accreditation. Access this URL and copy the code to your terminal. This works as a confirmation of your identity.

5. Test it!

Execute the command below to test your integration in the terminal.

$gactions test --action_package action.json --project 

With all steps executed, your integration is done and you can test your virtual agent. Follow the Google documentation to test it and publish.

Facebook Messenger connector

To configure the Messenger connector, you must access the Facebook for Developers console and have access to eva’s MySQL database. Then, execute the following steps.

1. Create your Facebook App

In the Facebook for Developers console, create a new App or use an existing one of your choice.

2. Add Messenger configuration

In the App Home, click on the Set Up button in the Messenger box.

If this box does not appear to you, click on the plus button besides the PRODUCTS label in the left menu.

​

3. Get your Facebook Page ID and Name

In Facebook, access the page in which you want to enable the messenger chat and copy the Page ID and Page Name. This information will be used in the next step.

The Page ID can be found in the URL after you access your page. For example:

https://www.facebook.com/MyFacebookPage-105498651278284/?modal=admin_todo_tour&ref=admin_to_do_step_controller

The Page ID above is 105498651278284.

The Page Name is the same that appears on the screen.

4. Select the channel and configure a token in eva

Access eva’s database and fetch the channel ID. To do that, first check your virtual agent id through the URL in the Cockpit. After selecting it, the number between the slashes, after the /home/ is your virtual agent id.

For example, if theURL shows:

​https://mybot.eva.bot/home/12/dialogmanager/workspace​

The virtual agent ID in this case is 12.

With this ID, run the following command on the MySQL database:

SELECT   id,   name FROM   channel WHERE   removed = 0    AND botId = < BOT_ID > ;

This will return a list of channels. Find the one to integrate with Facebook Messenger and copy the ID of that channel. This will be used it in the next SQL command.

Choose a security token. This can be any sentence to be used on both eva and Facebook to check that your Facebook Developer App and eva instance are yours. For example, a token could be simply “eva-facebook-security-token”.

Now, execute the following command replacing the values:

insert into   facebook_configuration (pageId, pageName, hubToken, pageAccessToken, channelId) values   (       < PAGE_ID > , '<PAGE_NAME>,' < TOKEN > ','', < CHANNEL_ID >    );

5. Configure Webhook

On Facebook for Developers console, go to the Messenger > Settings menu (if you clicked on the “Set Up” button before, you should be on this page already) and click on the “Add Callback URL” in the Webhooks box.

In the modal that opens, the Callback URL is provided by your eva’s installation administrator. It must be a URL ending in /fb/webhook.

Example URL: https://facebook-myeva.eva.bot/fb/webhook

In the Verify Token field, put the same token created before and click on the Verify and Save button.

This step configures how Facebook will call eva.

6. Select a Facebook Page

In the Webhooks box, click the Add or Remove Pages button and select which page you want to use. You will have to give the Facebook for Developers permission to access your account for this step to work.

A table will appear with the columns Pages and Webhooks. Click on the Add Subscriptions button and select the messages and messages_postbacks options.

​

Save it.

On the Access Tokens box, click the Generate Token button for your page and copy the token, it will be used to update the facebook_configuration table.

7. Configure the page token in eva

The final step for configuring the integration is to update the database with the page token. Execute the command below in your MySQL database replacing the page token and page id.

  update   facebook_configuration set   pageAccessToken = '<PAGE_TOKEN>' where   pageId = '<PAGE_ID>';

8. Test it!

To test your virtual agent, enable the chat button in the Facebook Page by clicking the “Add button” on the top right and select the “Send message” option. You are now ready to test your virtual agent.

Important:

• This manual shows how to integrate a virtual agent with Facebook in development mode. This will not make it available to all Facebook users. To set a virtual agent to production mode, you still have to follow Facebook compliance rules and submit it for evaluation.