Bots

Building your Bot on iAdvize
Let your bot interact with online visitors directly within iAdvize’s chatbox. The Bot plugin enables iAdvize's Admins and Managers to create users with the role “bot” from iAdvize’s administration. The scenario and availability of the bot are managed by your app.
In a nutshell, the Bot plugin:
  • Allows bots providers to create their connector thanks to the Developer Platform
  • Allows customers to connect their iAdvize account to a bot provider and connect bots seamlessly. These bots interact with iAdvize like a human agent
Bot plugin

What is a bot at iAdvize ?

A bot is a regular agent. It has all the properties of an agent and can interact with visitors.

Bots can

Among other things, bot are able to:
  • Be available to chat.
  • Handle a conversation in one language.
  • Reply to a user:
    • ask questions and act on replies;
    • send rich content such as links, carousels, and much more;
    • schedule messages to be sent later on;
  • Proactively send a message to the user (after the conversation has started)
  • Escalate a conversation to another operator.
  • Prequalify some visitor data (identification number, email address…).
  • And much more !

Bots cannot

This is what bots are not able to do:
  • Be part of a conversation at the same time than another agent
  • Proactively engage a conversation

Create and configure a bot in iAdvize

To be able to create a bot on the iAdvize platform, you will need to:
  • 1 - Create a bot application, in the dev platform
  • 2 - Browse, find and install this newly created bot application, in the marketplace tab of your iAdvize administration
  • 3 - Create a bot agent selecting the freshly installed bot application
  • 4 - Configure some rules to route incoming conversations to your bot
In order to be be able to complete this process you will have to implement the Bot creation flow first (or you will be stuck at the “Create bot agent” step)

In the dev platform

Creating a bot application in the developer platform is quite straightforward.

Create a bot connector

First, you hav to be logged in. Then go to “My apps” section, and click on “Build”. In our case we will call it “My bot”. To build a bot, you need to go to “Plugins” then select “Bot”. You have just one URL to set: the base URL of your connector. All the requests will go to this URL. Note that it has to be secured with HTTPS.
Click on save and… congratulations! You created your bot application. Of course this is just a stub. If you want this to be fully functional you have to implement the flows listed in the “Implement a bot” section (link).
Create bot connector

In the admin

Install the bot connector

In the admin, go to “Apps” and mind to select the project you want to install your connector on. In the list, find your connector, in our case the “My bot” section. Click on the card. You should land on an installation page such as:
Install a bot connector
You just have to click on “Install” and go through the installation process. Finalise the installation by clicking on “Install” and you are done. You just enabled some bot capabilities on the project you selected. It means that from now on, you can create an operator of type Bot 🎉.

Create a bot agent

In the Automation menu, then Bots, click on "Create a bot".
Select "External" then "Create a bot".
Create a bot agent
If you do not have any bot application installed on your iAdvize project, you will not see the “External” option in this window.
Fill in the different information of your bot:
Bot agent details
A bot operator is associated with ONE and only ONE language. So, if you want your bot to answer several languages, you have to create multiple bot operators.
Make sure you specify the right language because you can't change the language of a bot.

Chat with your bot

To be able to chat on iAdvize you need to take several steps:
  1. 2.
    Create a campaign
  2. 3.
    Create a targeting rule
  3. 4.
    Create a routing group
  4. 5.
    Create a routing rule

Create a campaign

In the admin, go to “Engagement”. Create a new campaign such as:
Create a bot campaign

Create a targeting rule

Now we need to define “engagement rules” i.e. how to target the visitor. Click on the “➕” and create a rule “Bot”. In our case, we will define that the button is being displayed when the current url contains the name “bot”. Which means you can add ?bot to any url and it will display the notification.
Create a targeting rule
Add the rule, and publish your campaign.

Create a routing group

It is no longer necessary to manually create a routing group since it is automatically created for each bot you create via the "Automation" section.

Create a routing rule

To finish, we need to create a routing rule. Go to “Routing”, in the upper left select picker, select “Routing rules” and create a rule “Bot targeting”, for the “Bot” notification, that will handover the conversations to the agents of group “[NAME OF YOUR BOT] chatbot routing group”. Such as:
Create a bot distribution rule

Check that everything is correctly setup

Go to “Campaigns” and click on the “edit” button. If you did everything correctly you should see that your campaign is routed this way:
Check targeting rule
To sum up, you created a campaign that you associated some engagement rules (when the visitor will see the notification) with, some targeting rules (to which agents the conversations should be handed to).
Last but not least let's trigger the chat. Go to the website you installed the iAdvize tag on. Just append ?bot to the current URL and reload the page. You should see the chat. You are ready to chat! 🎉

Implement a bot

To have a fully functional bot, you will be required to implement two distinct sets of endpoints:
  • several endpoints to create and configure your bot from iAdvize UI
    • GET /external-bots to list available scenarios
    • PUT /bots/:idOperator to create a bot
    • GET /bots/:idOperator to retrieve a bot details
    • GET /availability-strategies to define when the bot is available
  • three endpoints to handle a conversation flow
    • GET /bots/:idOperator/conversation-first-messages to return the messages to be displayed before the conversation starts
    • POST /conversations/ to create a new conversation
    • POST /conversations/:idConversation/messages to reply to a user
⚠️ Please note that all endpoints are subject to a 10 second timeout except for GET /bots/:idOperator/conversation-first-messages which has a 2 second timeout.

Implement the bot creation flow

A bot gets created when an admin creates a new agent of type “Bot” under the “People” section. Several information are required to be able to create a bot:
  • which scenario it can be associated to
  • what is the availability strategy associated to the bot
Bot creation flow

List available scenarios

First, you need to implement the GET /external-bots endpoint to list all the scenarios a new bot can be associated to. This route is called by iAdvize during the bot creation process and the result will appear directly in the scenario select picker.
⚠️ A scenario can only be associated to only one bot agent, which means if you have two bot operators, you need to provide at least two scenarios. ⚠️
Request - GET /external-bots
Query parameter
In
Description
Type
Example
idConnectorVersion
Query
Connector version identifier
Uuid
c008849d-7cb1-40ca-9503-d6df2c5cddd8
idWebsite
Query
Project identifier on which your connector is installed on
String
ha-123
Expected Response format
Field
In
Description
Type
Required
Example
idBot
Body
Scenario identifier in integrator environment.
String
my_scenario_id_1
name
Body
Name of the scenario
String
Scenario 1
description
Body
Short description of the scenario
String
This scenario will ask your customers to provide some data about their orders
editorUrl
Body
Url of integrator bot editor interface, useful if you have a UI for editing scenarios
String
Expected response example
[
{
"idBot": "my_scenario_id_1",
"name": "Scenario 1",
"description": "In this scenario, the bot will ask your customers to provide some data about their orders",
"editorUrl": "http://your-saas/editor/my_scenario_id_1"
},
{
"idBot": "my_scenario_id_2",
"name": "In this scenario, the bot will ask your customers to provide some data about their orders",
"editorUrl": "http://your-saas/editor/my_scenario_id_2"
}
]
Note: you can validate your response data format with the associated json schema.
It will look like this in the UI.
Scenario select picker

Create and modify a bot

This endpoint is being called when a user finalises the bot creation or when bot information are being updated (such as name, scenario association…).
Request - PUT /bots/:idOperator
Parameters
In
Description
Type
Example
idOperator
Path
iAdvize bot operator identifier that we associate to your bot scenario
String
ha-456678
idConnectorVersion
Query
Connector version identifier
Uuid
c008849d-7cb1-40ca-9503-d6df2c5cddd8
idWebsite
Query
Project identifier on which your connector is installed on
String
ha-123
Field
In
Description
Type
Example
name
Body
Bot name on your platform
String
My bot
pseudo
Body
Bot pseudo used during the conversation
String
Botty
language
Body
Language spoken by the bot
String - ISO 3166-1 alpha-2
fr
distributionRules
Body
Distribution rule that can be used inside transfer replies
Array
distributionRules.id
Body
Distribution rule identifier
Uuid
ef4670c3-d715-4a21-8226-ed17f354fc44
distributionRules.label
Body
Distribution rule label
String
Distribution rule label
external.idBot
Body
Existing bot unique identifier for this connector
String
my_scenario_id_1
Request example
{
"name": "My first bot !",
"pseudo": "Botty",
"language": "fr",
"distributionRules": [
{
"id": "ef4670c3-d715-4a21-8226-ed17f354fc44",
"label": "Distribution rule label"
}
],
"external": {
"idBot": "my_scenario_id_1"
}
}
Response format
Field
In
Description
Type
Required
Example
idOperator
Body
iAdvize bot operator identifier
String
ha-456678
external
Body
Associated scenario
External
external.idBot
Body
Bot identifier on your platform
String
my_scenario_id_1
external.name
Body
Bot name on your platform
String
Scenario 1
external.description
Body
Bot description on your platform
String
In this scenario, the bot will ask your customers to provide some data about their orders
external.editorUrl
Body
Bot edition url on your platform
String - URL
createdAt
Body
Creation date of you bot
String - ISO 8601
2017-11-22T12:04:00Z
updatedAt
Body
Last modification date of your bot
String - ISO 8601
2017-11-22T12:04:00Z
Response example
{
"idOperator": "ha-456678",
"external": {
"idBot": "my_scenario_id_1",
"name": "Scenario 1",
"description": "In this scenario, the bot will ask your customers to provide some data about their orders",
"editorUrl": "http://your-saas/editor/my_scenario_id_1"
},
"createdAt": "2017-11-22T12:04:00Z",
"updatedAt": "2017-11-22T12:04:00Z"
}
Note: You can validate your response data format with the associated json schema.

Get bot

When an admin wants to edit a bot user, we have to first load the existing information related to this bot. The GET endpoints allow you do give back those information.
Request - GET /bots/:idOperator
Parameters
In
Description
Type
Example
idOperator
Path
iAdvize bot operator identifier that we associate to your bot scenario
String
ha-456678
idConnectorVersion
Query
Connector version identifier
Uuid
c008849d-7cb1-40ca-9503-d6df2c5cddd8
idWebsite
Query
Project identifier on which your connector is installed on
String
ha-123
Response format
Field
In
Description
Type
Required
Example
idOperator
Body
iAdvize bot operator identifier
String
ha-456678
external
Body
Associated scenario
External
external.idBot
Body
Bot identifier on your platform
String
my_scenario_id_1
external.name
Body
Bot name on your platform
String
Scenario 1
external.description
Body
Bot description on your platform
String
In this scenario, the bot will ask your customers to provide some data about their orders
external.editorUrl
Body
Bot edition url on your platform
String - URL
createdAt
Body
Creation date of you bot
String - ISO 8601
2017-11-22T12:04:00Z
updatedAt
Body
Last modification date of your bot
String - ISO 8601
2017-11-22T12:04:00Z
Response example
{
"idOperator": "ha-456678",
"external": {
"idBot": "my_scenario_id_1",
"name": "Scenario 1",
"description": "In this scenario, the bot will ask your customers to provide some data about their orders",
"editorUrl": "http://your-saas/editor/my_scenario_id_1"
},
"createdAt": "2017-11-22T12:04:00Z",
"updatedAt": "2017-11-22T12:04:00Z"
}

Get availability

This endpoint will be called on a frequent basis (as of now, every second) and will indicate whether a bot agent is online or not, hence being its availability.
Request - GET /availability-strategies
Parameters
In
Description
Type
Example
idOperator
Query
iAdvize bot operator identifier that we associate to your bot scenario
String
ha-456678
idConnectorVersion
Query
Connector version identifier
Uuid
c008849d-7cb1-40ca-9503-d6df2c5cddd8
idWebsite
Query
Project identifier on which your connector is installed on
String
ha-123
Response format
Field
In
Description
Type
Required
Example 1
Example 2
strategy
Body
How we should aggregate the availability if several distribution rules are provided
One of: atLeastOne, all, notAvailable, customAvailability
atLeastOne
customAvailability
distributionRulesToCheck
Body
All distribution rules we should check for availability. This is subset of DistributionRules returned by the Get bot endpoint.
Array of Uuid
Required if strategy is equal to atLeastOneor all
ef4670c3-d715-4a21-8226-ed17f354fc44, fab46f63-a61b-4aec-930b-21a438863a6c
availability
Body
Allow the connector to handle the availability of the bot
Boolean
Required if strategy is equal to customAvailability
true
Response example 1: bot is available only if the distribution rule to check returns true
[
{
"strategy": "atLeastOne",
"distributionRulesToCheck": [
"ef4670c3-d715-4a21-8226-ed17f354fc44",
"fab46f63-a61b-4aec-930b-21a438863a6c"
]
}
]
Response example 2: bot is always available
[
{
"strategy": "customAvailability",
"availability": true
}
]
Note: You can validate your response data format with the associated json schema.

Implement the conversation flow

A conversation is typically initiated by a user. The bot can reply to user’s message, which means that iAdvize will call your endpoints when a message is received in the conversation.
To fully handle a conversation you only need to implement 3 endpoints:
  • GET /bots/:idOperator/conversation-first-messages to return the first messages you want to send as soon as the visitor opens up the chatbox (before the conversation really starts)
  • POST /conversations to handle a new conversation creation
  • POST /conversations/:conversationId/messages to receive messages from the visitor and reply to the visitor. Mind that all the messages posted in a conversation will result into this API call (which means you will also receive your own replies).
Conversation flow diagram
Here is a full conversation example:
Time
Bot Agent
Visitor
Text
Bot response
Calls to bot connector
Explanation
00:00
“Hi, are you there ? Shall we begin ?”
POST /conversations
Create a conversation in the bot connector
(empty replies)
Response
00:00
POST /conversations/:idConversation/messages “Hi, are you there ? Shall we begin ?”
Reply to the first user’s message
⟸ ⟸ ⟸
Await 5s “How are you ?” “Fine” or “Bad” Await 3 minutes “Are you there ?”
Response
00:05
“How are you ? ”
POST /conversations/:idConversation/messages “How are you ?”
Do not reply to your own scheduled message (filter on author operator)
⟸ ⟸
(empty replies)
Response
🕐
03:05
“Are you there ?”
POST /conversations/:idConversation/messages “Are you there ?”
Do not reply to your own scheduled message
(empty replies)
Response
03:12
“Yes I'm here, sorry"
POST /conversations/:idConversation/messages “Yes I’m here, sorry ?”
Reply to the user’s message by repeating the question
Await 1s “How are you ?” “Fine” or “Bad”
Response
03:13
“How are you ?”
POST /conversations/:idConversation/messages “How are you ?”
Do not reply to your own message
(empty replies)
Response
03:42
“Good”
POST /conversations/:idConversation/messages “Good”
User received quick-reply clicked on good, take action action accordingly
⟸ ⟸
Await 1s Ok, i'm transferring you to a human" transfer Await 20s “Transfer failed, please try again later” close
Response
Transfer the user, and notify the user about it. Schedule a message in case the transfer fail. The message is not going to be sent if the transfer is successful
03:43
“Ok, i'm transferring you to a human”
POST /conversations/:idConversation/messages “Ok, i'm transferring you to a human"
Do not reply to your own message
(empty replies)
Response

Send messages before the conversation starts

This endpoint is used if you want your bot to initiate a conversation with new visitors. It should return the first messages you want to send as soon as the visitor opens up the chatbox, before the first visitor message.
⚠️ Please note that your bot must return a response in less than 2 seconds. Otherwise, you'll receive a timeout and the bot messages will not be displayed to the user.
Request - GET /bots/:idOperator/conversation-first-messages
Parameters
In
Description
Type
Example
idConnectorVersion
Query
Connector version identifier
String
c008849d-7cb1-40ca-9503-d6df2c5cddd8
idOperator
Path
iAdvize bot operator identifier that we associate to your bot scenario
String
ha-123
Response format
Field
In
Description
Type
Required
Example
replies
Body
Array of replies
Array or Reply
reply.type
Body
Reply/action type
message (other types will be ignored)
reply.payload
Body
Typed payload of the message
One of Payload object see Payload objects for more details
reply.quickReplies
Body
Quick replies proposed to the visitor
Array of Quick Reply object see Quick reply object for more details
Response example
{
"replies":[
{
"type":"message",
"payload":{
"contentType":"text",
"value":"Hi, my name is robot and I'm here to help"
},
"quickReplies":[]
},
{
"type":"message",
"payload":{
"contentType":"text",
"value":"How can I help you ?"
},
"quickReplies":[
{
"contentType":"text/quick-reply",
"value":"I didn't receive my order"
},
{
"contentType":"text/quick-reply",
"value":"Payment problem"
}
]
}
]
}
Note: You can validate your response data format with the associated json schema.

Create a conversation

Everytime a conversation starts, this endpoint is called. It allows iAdvize to notify your bot a conversation starts.
⚠️ In most cases, leave the replies array empty as another call to POST /conversations/:idConversation/messages is triggered right after POST /conversations. It will be the right time to answer the visitor.
⚠️ But when a first chatbot handled the conversation and transferred it to your chatbot, the history field will contain an operator message "TRANSFERRED". If so, you must fill the "replies" tab in your response.
Request - POST /conversations
Parameters
In
Description
Type
Example
idConnectorVersion
Query
Connector version identifier
String
c008849d-7cb1-40ca-9503-d6df2c5cddd8
idWebsite
Query
Unique identifier of the website on which your connector is installed