Configuration flow

Method	Endpoint	Description
GET	/external-bots	to provide your bot scenarios to iAdvize
PUT	/bots/:operatorId	to handle creation and modification of your external bot inside the iAdvize admin
GET	/bots/:operatorId	to provide your external bot details
GET	/availability-strategies	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

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

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"
    }
]

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

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	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 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	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

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"
    }
}

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	✓	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

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.

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

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

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	✓	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

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"
}

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

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

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: 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

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

[
    {
        "strategy": "atLeastOne",
        "distributionRulesToCheck": [
            "ef4670c3-d715-4a21-8226-ed17f354fc44",
            "fab46f63-a61b-4aec-930b-21a438863a6c"
        ]
    }
]

Example 2: always available

In this case, your external bot will still be considered available.

[
    {
        "strategy": "customAvailability",
        "availability": true
    }
]

You can validate your response data format with the associated json schema