Developer Platform
  • Home
  • Getting Started
    • General Information
    • Features Overview
    • Security
  • APPs
    • Public Apps
      • Shopify
      • Salesforce
      • Zendesk
      • Google Analytics
    • Build your App
      • Getting started
      • My Apps
      • App information
      • App Parameters
      • App Plugins
      • Add Webhooks
      • Submit your Apps
      • App security
      • Developer Policy
  • Use Cases
    • Copilots
      • Product Catalog sync through API
      • FAQ sync through API
    • Visitor experience
      • Integrating custom buttons into your site
      • Check availability before escalating to iAdvize
      • Authenticated Messaging
        • Introduction
        • Web client-side implementation
          • Authenticated Messaging overview
          • Brief timeline of the integration process
          • How to enable authenticated mode in the administration portal?
          • How to implement the customer authentication backend (token provider)?
          • How to authenticate with iAdvize in client's website?
          • How to deal with activation success or failure?
          • How to logout?
          • Compatibility with Mobile SDK
          • FAQ
        • Web backend implementation
          • Important information and recommendations
          • Signature and Encryption Detailed Process
          • Technical backend implementation
          • FAQ
      • Cross-domain Conversation Continuity
      • Customize replies with Markdown
    • Agent workspace
      • Custom App example and step-by-step tutorial
        • Get Started
        • Work with the Desk
        • Intent / Trigger
        • JWT
        • References
    • Administration
      • Users
        • SAML SSO Authentication - Implementation Guide
        • Create, update and delete users via API
        • Manage the availability of your users with the iAdvize API
        • Integrate the iAdvize conversation panel into an existing tool
    • Data & Analytics
      • Anonymize a conversation or visitor data
      • Create a custom dashboard
      • Find contact data using GraphQL
      • Retrieve conversations data
      • Retrieve messages exchanged within a conversation
  • Technologies
    • GraphQL API
      • Terminology
      • Reference
      • Authentication
      • Schema lifecycle
      • Error Management
      • Pagination
    • REST API (deprecated)
      • Statistic (deprecated)
      • Group (deprecated)
      • Call meeting (deprecated)
      • Operator (deprecated)
      • Skill (deprecated)
      • Transaction (deprecated)
      • Visitor (deprecated)
    • Webhooks
      • Reference
      • Guides
    • Desk events
      • Reference
    • Web & Mobile SDK
      • Javascript Web SDK
        • Reference
      • Javascript Callbacks
        • Reference
        • Guides
      • Mobile SDK
        • Fourme (latest)
        • Epoisses
        • Dauphin
        • Cantal
        • 🤝Support Policy
        • 🤔Frequently Asked Questions
    • Custom App
    • External Bot
      • Implementation
        • Configuration flow
        • Conversation flow
        • Conversation objects
      • Configuration
      • FAQ
      • Best practices
Powered by GitBook
On this page
  • How it works?
  • Provide your bot scenarios to iAdvize
  • GET /external-bots
  • Expected response from your API
  • Handle creation and modification of your external bot inside the iAdvize admin
  • PUT /bots/:operatorId
  • Expected response from your API
  • Provide your external bot details
  • GET /bots/:operatorId
  • Expected response from your API
  • Define the availability strategy of your external bot
  • GET /availability-strategies
  • Expected response from your API

Was this helpful?

  1. Technologies
  2. External Bot
  3. Implementation

Configuration flow

PreviousImplementationNextConversation flow

Last updated 1 year ago

Was this helpful?

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

Bot creation flow

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

✓

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

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

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

✓

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

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

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

Scenario select picker

Language spoken by the bot

Note: You can validate your response data format with the associated .

You can validate your response data format with the associated

json schema
json schema
json schema
http://your-saas/editor/my_scenario_id_1
List of available languages
http://your-saas/editor/my_scenario_id_1
http://your-saas/editor/my_scenario_id_1