Configuration flow
Method | Endpoint | Description |
---|---|---|
|
| to provide your bot scenarios to iAdvize |
|
| to handle creation and modification of your external bot inside the iAdvize admin |
|
| to provide your external bot details |
|
| to provide the availability strategy of your external bot to iAdvize |
Please note that all endpoints are subject to a 10 seconds timeout
How it works?
A bot gets created when an admin creates a new agent of type “Bot” under the “Automation” 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
Provide your bot scenarios to iAdvize
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 operator, which means if you have two bot operators, you need to provide at least two scenarios.
GET /external-bots
GET /external-bots
Query parameter | In | Description | Type | Example |
---|---|---|---|---|
idConnectorVersion | Query | Connector version identifier | UUID |
|
idWebsite | Query | Project identifier on which your connector is installed on | String |
|
Expected response from your API
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 | ✓ |
Example
You can validate your response data format with the associated json schema
It will look like this in the UI.
Handle creation and modification of your external bot inside the iAdvize admin
This endpoint is being called when a user finalises the bot creation or when bot information are being updated (such as name, scenario association…).
PUT /bots/:operatorId
PUT /bots/:operatorId
Parameters | In | Description | Type | Example |
---|---|---|---|---|
operatorId | Path | iAdvize bot operator identifier that we associate to your bot scenario | String | ha-456678 |
idConnectorVersion | Query | Connector version identifier | UUID |
|
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 List of available languages | 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 |
|
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 |
Example
Expected response from your API
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 |
Example
Note: You can validate your response data format with the associated json schema.
Provide your external bot details
When an admin wants to edit a bot user, we have to first load the existing information related to this bot. This endpoints allows you do give back those information to iAdvize.
GET /bots/:operatorId
GET /bots/:operatorId
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 |
|
idWebsite | Query | Project identifier on which your connector is installed on | String | ha-123 |
Expected response from your API
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 |
Example
Define the availability strategy of your external bot
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.
GET /availability-strategies
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 |
|
idWebsite | Query | Project identifier on which your connector is installed on | String | ha-123 |
Expected response from your API
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: | ✓ |
|
|
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 | 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 | true |
Example 1 : the availability of your bot depends on the availability of another iAdvize routing/distribution rule
In this case, your external bot will be available only if atLeastOne
iAdvize distribution rules to check returns true
Example 2: always available
In this case, your external bot will still be considered available.
You can validate your response data format with the associated json schema
Last updated