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
A bot is a regular agent. It has all the properties of an agent and can interact with visitors.
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 !
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
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)
Creating a bot application in the developer platform is quite straightforward.
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, 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 🎉.
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.
To be able to chat on iAdvize you need to take several steps:
- 2.Create a campaign
- 3.Create a targeting rule
- 4.Create a routing group
- 5.Create a routing rule
In the admin, go to “Engagement”. Create a new campaign such as:

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.

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.
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
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! 🎉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 scenariosPUT /bots/:idOperator
to create a botGET /bots/:idOperator
to retrieve a bot detailsGET /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 startsPOST /conversations/
to create a new conversationPOST /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.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
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"
}
]
It will look like this in the UI.

Scenario select picker
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"
}
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"
}
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 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 |
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
}
]
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 creationPOST /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 | |
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 | | | |
reply.quickReplies | Body | Quick replies proposed to the visitor | | |
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"
}
]
}
]
}
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 |
---|