# Configuration flow
MethodEndpointDescription
GET/external-botsto provide your bot scenarios to iAdvize
PUT/bots/:operatorIdto handle creation and modification of your external bot inside the iAdvize admin
GET/bots/:operatorIdto provide your external bot details
GET/availability-strategiesto provide the availability strategy of your external bot to iAdvize
{% 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 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 | ✓ | | #### **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 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** ```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 | ✓ | | | 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 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 | ✓ | | | 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 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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.iadvize.dev/technologies/external-bot/implementation/configuration-flow.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.