# Configuration flow

<table><thead><tr><th width="109">Method</th><th width="279">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/external-bots</code></td><td>to provide your bot scenarios to iAdvize</td></tr><tr><td><code>PUT</code></td><td><code>/bots/:operatorId</code></td><td>to handle creation and modification of your external bot inside the iAdvize admin</td></tr><tr><td><code>GET</code></td><td><code>/bots/:operatorId</code></td><td>to provide your external bot details</td></tr><tr><td><code>GET</code></td><td><code>/availability-strategies</code></td><td>to provide the availability strategy of your external bot to iAdvize</td></tr></tbody></table>

{% hint style="danger" %}
Please note that all endpoints are subject to a **10 seconds timeout**
{% endhint %}

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

![Bot creation flow](https://raw.githubusercontent.com/iadvize/documentation/master/docs/assets/images/plugins/bot-scenarios-operator-flow.jpg)

## Provide your bot scenarios to iAdvize <a href="#list-available-scenarios" id="list-available-scenarios"></a>

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.

{% hint style="warning" %}
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.
{% endhint %}

### **`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**

```json
[
    {
        "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"
    }
]
```

{% hint style="info" %}
**Y**ou can validate your response data format with the associated [json schema](https://developers.iadvize.com/json-schemas/bot/external-bot.json)
{% endhint %}

It will look like this in the UI.

![Scenario select picker](https://raw.githubusercontent.com/iadvize/documentation/master/docs/assets/images/bots/scenario-select-picker.png)

## Handle creation and modification of your external bot inside the iAdvize admin <a href="#create-and-modify-a-bot" id="create-and-modify-a-bot"></a>

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 | <p>Language spoken by the bot<br><br><a href="https://help.iadvize.com/hc/en-gb/articles/115000501467-Language-available#2-on-the-discussion-panel-and-the-visitors-side">List of available languages</a></p> | 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**

```json
{
    "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**

{% code overflow="wrap" fullWidth="false" %}

```json
{
    "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"
}
```

{% endcode %}

**Note:** You can validate your response data format with the associated [json schema](https://developers.iadvize.com/json-schemas/bot/bot.json).

## Provide your external bot details <a href="#get-bot" id="get-bot"></a>

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

```json
{
    "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 <a href="#get-availability" id="get-availability"></a>

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

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

```json
[
    {
        "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.

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

{% hint style="info" %}
You can validate your response data format with the associated [json schema](https://developers.iadvize.com/json-schemas/bot/availability-strategies.json)
{% endhint %}