Comment on page

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.​Install the iAdvize tag on your website​
2.Create a campaign
3.Create a targeting rule
4.Create a routing group
5.Create a routing rule
Create a campaign
In the admin, go to “Engagement”. Create a new campaign such as:
​
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.
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
✓
​http://your-saas/editor/my_scenario_id_1​
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
✓
​http://your-saas/editor/my_scenario_id_1​
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
✓
​http://your-saas/editor/my_scenario_id_1​
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
String
ha-123
Field
In
Description

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

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	✓	http://your-saas/editor/my_scenario_id_1

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

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	✓	http://your-saas/editor/my_scenario_id_1
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

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 `atLeastOne`or `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

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

Field	In	Description	Type	Required
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