Configuration flow

PreviousImplementation NextConversation flow

Last updated 8 months ago

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

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

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

[
    {
        "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

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

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

String - ISO 3166-1 alpha-2

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

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

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

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

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

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

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

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