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.

Learn more about all Channel's features in eva

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 virtual agent's parameter screen:

Add the following parameter:

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

Name	Type	Required	Description
omniUrl	String	Yes	This URL is provided by infobip. Log in to the portal.infobip.com and access this site: https://dev.infobip.com/#programmable-communications/omni-failover/list-all-omni-failover-scenarios Copy the URL after the GET, remove the /scenarios at the end.
user	String	Yes	Your Infobip portal user
password	String	Yes	Password for the user above
whatsappNumber	String	Yes	The Whatsapp number given by Infobip
channel	String	Yes	Fixed value: “WHATSAPP”
keyword	String	Yes	The keyword used by eva to represent a channel

Example:

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

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.

Google	Link
Google Actions	https://console.actions.google.com
Google CLI	https://developers.google.com/actions/tools/gactions-cli

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":{
      "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.