Developer platform beta

General information

Welcome to iAdvize’s developer documentation! If you want to use our API, create integrations for your own personal use or to share with the rest of the world, you are in the right place.

Early November 2017, iAdvize will provide you with a Developer platform for you to easily publish your apps on our marketplace so that our users can install them directly from their administration interface.

Whether you are a developer, an integrator, a customer or just curious, here, you will find an overview of how to get started, our Developer Guidelines, our API with practical examples and a guide to build and publish your future integrations.

What is iAdvize?

iAdvize is a conversational marketing platform that enables businesses to engage their customers and prospects whether they’re on the website or on social media from one single messaging solution (chat, voice, video). Visitors can get real-time advice from customer service but also from advocates, members of the brand community via ibbü - our on-demand pool of experts.

Implementing iAdvize is child's play. You just have to insert a tag on each page of your website. Once the solution is deployed, your customer service and marketing teams are completely independent and can set up the solution as they wish.

The iAdvize platform has 2 interfaces:

  • The administration: administrators and managers of the solution can configure the platform's settings and monitor the agent's activity.

  • The agent's console panel: it gives superpowers to your agents. That's the place where professional agents or experts can respond intuitively to all the messages they receive.

iAdvize iAdvize

What is the Developer Platform?

The iAdvize Developer Platform allows developers to build apps and use our public APIs. Do you want to develop an app? We are providing you with documentation and a private testing environment. (The Developer Platform will be available in private beta from November, 2017.)

Why to build apps to iAdvize?

There are three main reasons for building an app with the iAdvize Developer Platform:

  • You build apps and publish them for our customer community. (We've got more than 500 customers to amaze!)
  • You build apps in private mode and make them available only for one or more specific customers
  • You get rewarded based on how frequently your apps are used

Here is the example of a potential protocol between iAdvize and a CRM software thanks to a connector: CRM Webhook

Getting Started

Do you want to join our developer community as a beta tester 🤘🏽? Follow these steps to be part of the adventure:

Get a Developer Account

To build apps that iAdvize’s customers can use, first, you need to get a developer account. The Developer Platform will be available in private beta version from November, 17. We invite you to apply to the early access program thanks to our online form.

  • Apply and share your integration project with our team,
  • The iAdvize team will contact you within 48 hours.

Features Overview

iAdvize's Developer Platform will provide you with some easy-to-use tools so you can:

  • Manager the privacy mode of your app for it to be public or private
  • Set up the authentication process for your app
  • Define custom settings such as object mapping (In progress)
  • Create plugins to enhance some of iAdvize's predefined features
  • Use outgoing webhooks to receive updates in real-time

Once your app is ready, you will be able to submit your connector for review. Then, the iAdvize team will review your app to make sure it fits the Developer Platform policies, and will get back to you within 48 hours (on working days). And then hurrah... You can publish your app on iAdvize’s marketplace!

Build apps

Once you are logged in your developer account, you are ready to build apps. So let's go through the different sections of the Developer Platform:

My apps

This is the place where you can see the list of all the apps you have built on iAdvize. You can also see their current status:

  • Published: your app is ready to be installed on the iAdvize Marketplace
  • Under review: your app has been submitted for review
  • Sandbox: you can edit your app

App information

This is where you will be able to define your app's profile. Also, this is where you can set the Privacy mode of your application: public or private.

How does the Private mode work? Your App can be available for all iAdvize's customers or for selected customers. Our team is still working on the accessibility mode under the Private mode. In alpha version, we will make it available manually for the specific customers you have selected.

App Authentication

The App Authentication section is where you can set the authentication information that the final user will have to enter in order to install your connector. Once the user authenticated, the connector will be able to access the right data from iAdvize and from the third-party app. For example, you can ask the user for his/her third app's email and password. Users will need to follow these authentication steps to install your app.

Define app's authentication parameters You can add parameters and define the type of entry you need (text, numeric, etc.).

  • Key: the key of your parameter according to your code.
  • Label: it’s the name of your parameter, this is what users will see.
  • Type: it defines the type of entry. (For instance: alphanumeric).

You can add as much parameters as you need. This is the first thing users will see once they click on the "install" button on the iAdvize Marketplace. Parameters appear to users according to their order of creation (the 1st entry created is the 1st on displayed on the page).

i.e. if your primary goal is to know your users’ usernames, it is the first information you should ask them for.

i.e. users might be required to authenticate with an email and a password. In this case, you need to create two different parameters, one for the email and one for the password.

Authentication

Users have to fill in the parameters during the installation process first, on the iAdvize Marketplace.

Authentication admin

App Settings

Just as in the section dedicated to your app's authentication, you are able to set the parameters that users will need to install your connector. These are the parameters that the iAdvize administrator will fill in to install and configure your connector from the iAdvize Marketplace.

Define your app's settings parameters

You can add as many parameters as the installation and configuration of your application requires. For each of these parameters you will have to specify the type of input required.

Label: it is the name of your parameter. (This is what the users will see). For instance it could be: Username Type: it defines the type of entry. (For instance: alphanumeric) *ID: the identifier (key) of your parameter according to your code.

These configuration steps will take place immediately after authentication (if any). The order of appearance of the steps depends on their order of creation. The first created parameter will appear first and the last created parameter will appear last to the user.

Setting

App Plugins

Use plugins to enhance the iAdvize interface by adding or editing predefined features.

Plugins are basically HTTP endpoints whose json responses fit the plugin json-schema. For each plugin one or more endpoint have to be defined. When a plugin is used on user interface, we will make a GET http call to endpoint with documented query parameters. Your http response have to comply with plugin json-schema.

The plugins already available are:

  • The product List (on the discussion panel)
  • The visitor profile (on the discussion panel)
  • The conversation closing form (on the discussion panel)
  • The bot (add an external bot within iadvize chatbox)

Product list

The integration of the product list enables iAdvize's Console panel users to browse a product catalog from the iAdvize discussion panel. Agents can look for a product while they are chatting and send it in just a click within their conversation.

Products are displayed in a popup window just over the conversations view: When shared, visitors can see their image, title, availability and price. By clicking on the "view product" button, visitors are redirected to the product page on your website.

Product list

Add the Product list plugin

To make sure your connector uses the Product list plugin correctly, all you have to do is to declare:

  • The product list URL - this is your catalog’s URL
  • The categories url - this is where your connector will get the list of your product categories

Categories data

Request - GET method
Query parameterDescriptionValues
idConnectorVersionConnector version id?idConnectorVersion=123
idParentUnique identifier of the parent category?idParent=123
idWebsiteUnique identifier of the website on which your connector is installed?idWebsite=123
idOperatorUnique identifier of the operator loading the categories?idOperator=9999
limitMaximum number of resources per page?limit=10
offsetNumber of resources skipped before beginning to return resources?offset=10
Response - Array of categories
[
    {
        "id": "123",
        "idParent": "123",
        "label": "category",
        "products": [
            "123",
            "456"
        ],
        "productsCount": 3
    },
    {
        "id": "456",
        "idParent": null,
        "label": "category",
        "products": null,
        "productsCount": 7
    }
 ]
FieldDescriptionValuesRequired
idUnique identifierInteger
idParentUnique identifier of the parent categoryInteger
labelLabelString
productsproductsArray of strings
productsCountNumber of productsInteger

Products data

Request - GET method
Query parameterDescriptionValues
idConnectorVersionConnector version id?idConnectorVersion=123
idCategoryCategory id?idCategory=123
idWebsiteUnique identifier of the website on which your connector is installed?idWebsite=123
idOperatorUnique identifier of the operator loading the products?idOperator=9999
limitMaximum number of resources per page?limit=10
offsetNumber of resources skipped before beginning to return resources?offset=10
searchQueryProduct search query?searchQuery=query
Response - Array of products
[
    {
        "id": "123",
        "title": "Product's title",
        "productUrl": "http://www.e-commerce.com/url-product",
        "brand": "brand",
        "description": "product's description",
        "shortDescription": "shrot description",
        "available": true,
        "imageUrl": "http://www.e-commerce.com/url-product-image.jpg",
        "reference": "reference",
        "priceCatalog": "99.9 €",
        "pricePromotion": "90 €",
        "priceSpecial": "80 €"
    },
    {
        "id": "456",
        "title": "Product's title",
        "productUrl": "http://www.e-commerce.com/url-product",
        "brand": null,
        "description": "product's description",
        "shortDescription": null,
        "available": true,
        "imageUrl": "http://www.e-commerce.com/url-product-image.jpg",
        "reference": null,
        "priceCatalog": "9.9 €",
        "pricePromotion": null,
        "priceSpecial": null
    }
]
FieldDescriptionValuesRequired
idUnique identifierInteger
titleTitleString
productUrlProduct's urlString
brandBrandString
descriptionDescriptionString
shortDescriptionShort descriptionString
availableAvailabilityBoolean
imageUrlImage's urlString
referenceReferenceString
priceCatalogPrice catalogString
pricePromotionPrice promotionString
priceSpecialPrice specialString

Visitor profile

The visitor profile plugin enables iAdvize's Console panel users to access to the visitor's CRM profile in a single click. Agents can overview the visitor's CRM profile in a new window while they are chatting. Operators can then edit it or simply look for information.

To be able to retrieve the CRM profile, iAdvize must be able to identify the visitor thanks to an email and/or an external ID.

Visitor profile

Add the visitor profile plugin In order to set the right plugin parameters, all you have to do is to declare:

  • The connector URL - this is your visitor's profile URL

Visitor profile data

Request - GET method
Query parameterDescriptionValues
emailVisitorVisitor email?emailVisitor=123
idConnectorVersionConnector version id?idConnectorVersion=123
idVisitorExternalVisitor external id?idVisitorExternal=123
idVisitorUniqueVisitor unique id?idVisitorUnique=123
idWebsiteUnique identifier of the website on which your connector is installed?idWebsite=123
operatorLocaleOperator locale?operatorLocale=en
idOperatorUnique identifier of the operator loading the visitor profile?idOperator=9999
Response - Array of fields
[
    {
        "id":"crm_profile_link",
        "label": "CRM profile",
        "value": "https://www.crm.fr/visitor-profile",
        "fieldType":"URL"
    },
    {
        "id":"crm_visitor_tag",
        "label": "CRM tag",
        "value": "tag",
        "fieldType": "TEXT"
    }
]
FieldDescriptionValuesRequired
idUnique identifierString
labelLabelString
valueValueString
fieldTypeField typeURL or TEXT

Conversation closing form

The conversation closing form plugin enables iAdvize's Console panel users to provide additional information manually at the end of conversation.

Conversation closing form plugin

Add the conversation closing form plugin

In order to set the right plugin parameters, all you have to do is to declare:

  • The connector URL - this is your form's url

Conversation Closing Form data

Request - GET method
Query parameterDescriptionValues
idConnectorVersionConnector version id?idConnectorVersion=123
idWebsiteUnique identifier of the associated website (assigned to you by iAdvize)?idWebsite=123
operatorLocaleOperator locale?operatorLocale=en
idOperatorUnique identifier of the operator loading the form?idOperator=9999
Response - Array of inputs
FieldDescriptionValuesRequired
idUnique identifierstring
idParentParent identifier, if the field depends on itstring
labelLabelstring
fieldTypeField typeTEXT, CHECKBOX or SELECT
isRequiredRequiredBoolean
optionsList of options object for SELECT typearray
options.labelLabel displayed for this optionstring
options.valueValue saved when option is selectedstring
[
    {
        "id": "create_crm_ticket",
        "label": "Create a CRM ticket",
        "fieldType": "CHECKBOX",
        "isRequired": true
    },
    {
        "id": "brand_name",
        "idParent": "1",
        "label": "Brand name",
        "fieldType": "TEXT",
        "isRequired": true
    },
    {
        "id": "ticket_priority",
        "idParent": "1",
        "label": "Priority",
        "fieldType": "SELECT",
        "isRequired": true,
        "options": [
            {
                "label": "Major",
                "value": "MAJOR",
            },
            {
                "label": "Minor",
                "value": "MINOR",
            },
            {
                "label": "Trivial",
                "value": "TRIVIAL",
            },
        ],
    }
]

External bot

Let your bot interact with online visitors directly within iAdvize’s chatbox. The External bot plugin enables iAdvize's Admins and Managers to create users with the role “bot” from iAdvize’s administration. The scenario and availability of the bot are managed by your app.

To put it in a nutshell, the External bot plugin:

  • Allows bots providers to create their connector thanks to the Developper Platform
  • Allows customers to connect their iAdvize account to a bot provider and connect bots seamlessly. These bots interact with iAdvize like a human agent.

Bot plugin

The External bot user flow

The iAdvize Administrator/Manager:

  • Activates your connector from the iAdvize marketplace,
  • Creates a new user with the role "bot" from the "People" section of iAdvize,
  • Select an external bot and a scenario,

Bot plugin

Add the External bot plugin To make sure your connector uses the External Bot plugin correctly, all you have to do is to declare the base url that will be postfixed by seven endpoints described below.

Operator form flow endpoints

There are 4 endpoints related to Operator form flow. This is related to the creation of an Operator with a Bot role, within iAdvize in order to link it to the External bot.

Bot plugin

List external bots (endpoint)
Request - GET /external-bots
Query parameterDescriptionValues
idConnectorVersionConnector version id?idConnectorVersion=123
idWebsiteUnique identifier of the website on which your connector is installed?idWebsite=123
Response
[
    {
        "idBot": "Hal12343",
        "name": "Hal",
        "description": "Hal is good, bro",
        "editorUrl": "http://your-saas/Hal12343/editor"
    },
    {
        "idBot": "brt123569",
        "name": "Bart Simpson",
        "editorUrl": "http://your-saas/brt123569/editor"
    },
]
FieldDescriptionValuesRequired
idBotUnique identifier of the botString
nameName of the botString
descriptionDescription of the botString
editorUrlUrl used to redirect user to your bot editorA valid URL
Modify bot information (endpoint)
Request - PUT /bots/:idOperator:
{
    "name": "Hal",
    "pseudo": "Hal is good, bro",
    "language": "fr",
    "distributionRules": [
        {
            "id": "ef4670c3-d715-4a21-8226-ed17f354fc44",
            "label": "Human SAV guys"
        }
    ],
    "external": {
        "idBot": "Hal12343"
    }
}
ParametersInDescriptionValues
idConnectorVersionQueryConnector version id?idConnectorVersion=123
idWebsiteQueryUnique identifier of the website on which your connector is installed?idWebsite=123
idOperatorPathiAdvize bot operator identifier that we associate to your bot scenario/bots/456678
FieldDescriptionValuesConstraints
nameBot name on your platformString
pseudoBot pseudo used during the conversationString
languageLanguage spoken by the botStringISO 3166-1 alpha-2
distributionRulesdistribution rule that can be used inside transfer repliesArray
distributionRules.idDistribution rule identifierStringUUID
distributionRules.labelDistribution rule labelString
external.idBotExisting bot unique identifier for this connectorString
Response
{
    "idOperator": "local-23232",
    "external": {
      "idBot":"R3R3ZFDKOEZ",
      "name": "Hal",
      "description": "Hal is good, bro",
      "editorUrl": "http://your-saas/R3R3ZFDKOEZ/editor"
    },
    "distributionRules": [
      { 
        "id": "ef4670c3-d715-4a21-8226-ed17f354fc44",
        "label": "Human SAV guys"
      }
    ],
    "createdAt": "2017-11-22T12:04:00Z",
    "updatedAt": "2017-11-22T12:04:00Z"
  }
FieldDescriptionValuesRequiredConstraints
idOperatoriAdvize bot operator identifierString
external.idBotBot identifier on your platformString
external.nameBot name on your platformString
external.descriptionBot description on your plateformString
external.editorUrlBot edition url on your platformStringURL
distributionRulesdistribution rule that can be used inside transfer repliesArray
distributionRules.idDistribution rule identifierStringUUID
distributionRules.labelDistribution rule labelString
createdAtCreation date of you botStringISO 8601
updatedAtLast modification date of your botStringISO 8601
Get bot information (endpoint)
Request - GET /bots/:idOperator:
ParametersInDescriptionValues
idConnectorVersionQueryConnector version id?idConnectorVersion=123
idWebsiteQueryUnique identifier of the website on which your connector is installed?idWebsite=123
idOperatorPathiAdvize bot operator identifier that we associate to your bot scenario/bots/456678
Response
{
    "idOperator": "local-23232",
    "external": {
        "idBot":"R3R3ZFDKOEZ",
        "name": "Hal",
        "description": "Hal is good, bro",
        "editorUrl": "http://your-saas/R3R3ZFDKOEZ/editor"
    },
    "distributionRules": [
        { 
            "id": "ef4670c3-d715-4a21-8226-ed17f354fc44",
            "label": "Human SAV guys"
        }
    ],
    "createdAt": "2017-11-22T12:04:00Z",
    "updatedAt": "2017-11-22T12:04:00Z"
}
FieldDescriptionValuesRequiredConstraints
idOperatoriAdvize bot operator identifierString
external.idBotBot identifier on your platformString
external.nameBot name on your platformString
external.descriptionBot description on your plateformString
external.editorUrlBot edition url on your platformStringURL
distributionRulesdistribution rule that can be used inside transfer repliesArray
distributionRules.idDistribution rule identifierStringUUID
distributionRules.labelDistribution rule labelString
createdAtCreation date of you botStringISO 8601
updatedAtLast modification date of your botStringISO 8601
Get bot availability strategies (endpoint)

Bot is ready and should be available accordingly to the availability strategy and distributions rules.

Request - GET /availability-strategies
ParametersInDescriptionValuesRequired
idConnectorVersionQueryConnector version id?idConnectorVersion=123
idWebsiteQueryUnique identifier of the website on which your connector is installed?idWebsite=123
idOperatorQueryiAdvize bot operator identifier that we associate to your bot scenario?idOperator=456678
Response
[
    {
        "strategy": "atLeastOne",
        "distributionRulesToCheck": [
            "ef4670c3-d715-4a21-8226-ed17f354fc44"
        ]
    }
]
[
    {
        "strategy": "customAvailability",
        "availability": true
    }
]
FieldDescriptionValuesRequiredConstraints
strategyHow we should aggregate the availability if several distribution rules are providedatLeastOne or all or notAvailable or customAvailability
distributionRulesToCheckAll distribution rules we should check for availability. This is subset of DistributionRules returned by the Get bot endpoint.Array of StringRequired if strategy is equal to atLeastOne or all
availabilityAllow the connector to handle the availability of the botBooleanRequired if strategy is equal to customAvailability

Conversation flow endpoints

There are 3 Conversation flow endpoints :

  • Each time a conversation is created, we call the conversation initialisation endpoint. In the current setup, the visitor is always the first to talk, so you should response with an empty array of replies.
  • This initialisation call will be immediatly followed by a call to the new message & reply reception endpoint, this second call will contain the first message of the visitor. You should response to this call with some reply (usually a welcoming message reply).
  • Be careful, from this point the calls to new message & reply reception endpoint can contains the visitor's messages or your own replies. See the example below.

Bot plugin

Here is a full conversation example :

  • 00:00 - The visitor sends "Hi, are you there ? Shall we begin ?" in the conversation. We call the new message reception endpoint with the message in the request. Your plugin response with an await 1 second and send an "How are you ?" message with two quick replies ("Fine" or "Bad").
  • 00:01 - Our operator/bot sends "How are you ?" in the conversation. We call the new message reception endpoint with this message in the request. Your plugin response with an await 3 minutes and send "Are you there ?" message.
  • 03:01 - Our operator/bot sends "Are you there ?", your plugin response with an empty array of replies.
  • 03:12 - The visitor sends "Yes I'm here, sorry", your plugin response with an await 1 second and send "How are you ?" message with two quick replies ("Fine" or "Bad").
  • 03:13 - Our operator/bot sends "How are you ?", your plugin response with an await 3 minutes and send "Are you there ?" message.
  • 03:42 - The visitor sends "BAD", the bot schedules a reply in 1 second with an "Ok, i'm transferring you to a human" message followed by a transfer.
  • 03:43 - Our operator/bot sends "Ok, i'm transferring you to a human", your plugin response with an immediate transfer.
Conversation initialisation (endpoint)
Request - POST /conversations
{
    "idOperator": "local-22",
    "idConversation": "f1c64107-25b0-4865-ad20-88419275eb64",
    "history": [
        {
            "idMessage": "42e3de6f-84f2-4883-b5d1-6710bc5dc488",
            "author": {
                "role": "operator"
            },
            "payload": {
                "contentType": "text",
                "value": "Please answer the following questions."
            },
            "createdAt": "2017-11-22T12:04:00Z"
        }
    ]
}
ParametersInDescriptionValuesRequired
idConnectorVersionQueryConnector version id?idConnectorVersion=123
idWebsiteQueryUnique identifier of the website on which your connector is installed?idWebsite=123
FieldDescriptionValuesConstraints
idOperatoriAdvize bot operator identifier that we associate to your bot scenarioString
idConversationConversation unique identifier, you can use it or return your own internal id in the response body. We will make the join for you.StringUUID
historyFirst messages of the conversationsArray
history.idMessageUnique identifier of this messageStringUUID
history.author.roleauthor of the messageoperator or visitor
history.payloadTyped payload of the messageObject
history.payload.contentTypeType of the message’s contentStringtext
history.payload.valueMessage contentString
history.createdAtDate the message was sentStringISO-8601
Response
{
    "idConversation": "a0c65ae0-4e04-4909-a5cc-80dd0f05de96",
    "idOperator": "local-22",
    "replies": [],
    "variables": [
        {
            "key": "visitor_state_of_mind",
            "value": "Ok"
        }
    ],
    "createdAt": "2018-07-16T13:53:57.961Z",
    "updatedAt": "2018-07-16T13:53:57.961Z"
}
FieldDescriptionValuesRequiredConstraints
idConversationConversation unique identifierStringUUID
idOperatoriAdvize bot operator identifier that we associate to your bot scenarioString
repliesArray of repliesArray
replies.typeReply/action typeawait or message or transfer or close
replies.duration.unitAwaiting unit of timemillis or seconds or minutesreplies.type == await
replies.duration.valueAwaiting value of timeLongreplies.type == await
replies.payloadTyped payload of the messageObjectreplies.type == message
replies.payload.contentTypeType of the message’s contenttext or text/quick-replyreplies.type == message
replies.payload.valueTextual content of the messageStringreplies.type == message
replies.quickRepliesQuick replies proposed to the visitorArrayreplies.type == message
replies.quickReplies.valueTextual content of the quick replyStringreplies.type == message
replies.quickReplies.idQuickReplyIdentifier of the quick replyStringreplies.type == message
replies.distributionRuleDistribution rules to transfer toStringreplies.type == transfer
variablesCollected variablesArrayUUID
variables.keyKey of the variable collectedString
variables.valueValue of the variable collectedString
createdAtCreation date of the conversationDateTimeISO-8601
updateAtDate of the last message receivedDateTimeISO-8601
New message & reply reception (endpoint)
Request - POST /conversations/:conversationId:/messages
ParametersInDescriptionValuesRequired
idConnectorVersionQueryConnector version id?idConnectorVersion=123
idWebsiteQueryUnique identifier of the website on which your connector is installed?idWebsite=123
{
    "idOperator": "local-23232",
    "message":   {
        "idMessage": "ba4e1f71-7012-4b1a-86c3-d2fce8883dc7",
        "author": {
            "role": "visitor"
        },
        "payload": {
            "contentType": "text",
            "value": "Hi, are you there ? Shall we begin ?"
        },
        "createdAt": "2017-11-22T12:04:00Z"
    }
}
FieldDescriptionValuesConstraints
idOperatoriAdvize bot operator identifier that we associate to your bot scenarioString
message.idMessageThe unique identifier for this messageUUID
message.author.roleThe author of the messagevisitor or operator
message.payloadTyped payload of the messageObject
message.payload.contentTypeType of the message’s contenttext
message.payload.valueTextual content of the messageString
message.createdAtDate the message was sentDateTimeISO-8601
Response
{
    "idConversation": "ce41ba2c-c25a-4351-b946-09527d8b940b",
    "idOperator": "local-423232",
    "replies": [
        {
            "type": "await",
            "duration": {
                "unit": "seconds",
                "value": 1
            }
        },
        {
            "type": "message",
            "payload": {
                "contentType": "text",
                "value": "How are you ?"
            },
            "quickReplies": [
                {
                    "contentType": "text/quick-reply",
                    "value": "Fine",
                    "idQuickReply": "1ef5145b-a9b6-4e86-8743-b6e3b4026b2c"
                },
                {
                    "contentType": "text",
                    "value": "Bad",
                    "idQuickReply": "13594c9b-dcff-4add-81fc-5e1093e443a7"
                }
            ]
        }
    ],
    "variables": [],
    "createdAt": "2017-11-22T12:04:00Z",
    "updatedAt": "2017-11-22T13:04:00Z"
}
FieldDescriptionValuesRequiredConstraints
idConversationConversation unique identifierStringUUID
idOperatoriAdvize bot operator identifier that we associate to your bot scenarioString
repliesArray of repliesArray
replies.typeReply/action typeawait or message or transfer or close
replies.duration.unitAwaiting unit of timemillis or seconds or minutesreplies.type == await
replies.duration.valueAwaiting value of timeLongreplies.type == await
replies.contentTyped payload of the messageObjectreplies.type == message
replies.content.contentTypeType of the message’s contenttext or text/quick-replyreplies.type == message
replies.content.valueTextual content of the messageStringreplies.type == message
replies.quickRepliesQuick replies proposed to the visitorArrayreplies.type == message
replies.quickReplies.valueTextual content of the quick replyStringreplies.type == message
replies.quickReplies.idQuickReplyIdentifier of the quick replyStringreplies.type == message
replies.distributionRuleDistribution rules to transfer toStringreplies.type == transfer
variablesCollected variablesArrayUUID
variables.keyKey of the variable collectedString
variables.valueValue of the variable collectedString
createdAtCreation date of the conversationDateTimeISO-8601
updateAtDate of the last message receivedDateTimeISO-8601
Get the conversation content (endpoint)
Request - GET /conversations/:conversationId:
ParametersInDescriptionValuesRequired
idConnectorVersionQueryConnector version id?idConnectorVersion=123
idWebsiteQueryUnique identifier of the website on which your connector is installed?idWebsite=123
idOperatorQueryiAdvize bot operator identifier that we associate to your bot scenario?idOperator=456678
Response
{
    "idConversation": "ce41ba2c-c25a-4351-b946-09527d8b940b",
    "idOperator": "local-232323",
    "replies": [
        {
            "type": "await",
            "duration": {
                "unit": "millis",
                "value": 10
            }
        },
        {
            "type": "message", #Enum that can take message|await|close|transfer
            "payload": {
                "contentType": "text",
                "value": "All Right, my job is done here."
             },
            "quickReplies": []
        },
        {
            "type": "transfer",
            "distributionRule": "ef4670c3-d715-4a21-8226-ed17f354fc44"
        },
        {
            "type": "close"
        }
    ],
    "variables": [
        {
            "key": "visitor_state_of_mind",
            "value": "Ok"
        }
    ],
    "createdAt": "2017-11-22T12:04:00Z",
    "updatedAt": "2017-11-22T12:23:00Z"
}
FieldDescriptionValuesRequiredConstraints
idConversationConversation unique identifierStringUUID
idOperatoriAdvize bot operator identifier that we associate to your bot scenarioString
repliesArray of repliesArray
replies.typeReply/action typeawait or message or transfer or close
replies.duration.unitAwaiting unit of timemillis or seconds or minutesreplies.type == await
replies.duration.valueAwaiting value of timeLongreplies.type == await
replies.contentTyped payload of the messageObjectreplies.type == message
replies.content.contentTypeType of the message’s contenttext or text/quick-replyreplies.type == message
replies.content.valueTextual content of the messageStringreplies.type == message
replies.quickRepliesQuick replies proposed to the visitorArrayreplies.type == message
replies.quickReplies.valueTextual content of the quick replyStringreplies.type == message
replies.quickReplies.idQuickReplyIdentifier of the quick replyStringreplies.type == message
replies.distributionRuleDistribution rules to transfer toStringreplies.type == transfer
variablesCollected variablesArrayUUID
variables.keyKey of the variable collectedString
variables.valueValue of the variable collectedString
createdAtCreation date of the conversationDateTimeISO-8601
updateAtDate of the last message receivedDateTimeISO-8601

Add webhooks

The webhook system allows external applications to subscribe to events (via callback URLs) to receive updates in real-time. When you build your app, you can subscribe to a list of events. When customers install your app, it automatically creates webhooks for these customers as well as for events based on your app's configuration.

This subscription is based on the events happening on different domains. See the list of events available in the Webhooks documentation.

You can create as much outgoing webhooks as you need. A webhook can cover several events. An event can be linked to a customer (example customers.website.created) or linked to a website (example customers.website.created)

  • Name of the webhook: an optional label you can give to the webhook
  • webhook URL: the server URL that will receive the webhook
  • Security token: Token provided by iAdvize (this field cannot be edited)
  • Content-type: Application / json ; Application / x-www-form-urlencoded
  • Events: you can select the events in the list. You can subscribe to all iAdvize events, all events of a specific domain, or only one event.

Submit your apps

Apps must be submitted to iAdvize for review. The versioning declaration must be done by the developer during the submission process. iAdvize will approve or refuse the app based on specific criteria. iAdvize will get in touch within 48 hours to the developers.

App security

For security reasons iAdvize provides you with a method to verify and secure your apps. You will be able to make sure that the payloads have not been subjected to modifications, and to verify its source in order for example to limit the requests to those coming from iAdvize.

Once your server is configured to receive payloads, you can set up a secret token and verify the information.

Set you secret token

First, you need to get one secret token depending on your connector. You can retrieve this token in the 'App information' section on our developer platform.

Validating payloads from iAdvize

Once the secret token set, iAdvize will create a hash signature. This hash signature is passed along with each request in the headers as X-iAdvize-Signature. Hash signature starts with algorithm name sha256= and is computed by hashing query string with HMAC hexdigest algorithm and your secret token as salt.

X-iAdvize-Signature: sha256=110e8400-e29b-11d4-a716-446655440000

You have to compute a new hash using your secret token, and to compare it with X-iAdvize-Signature and make sure it matches.

$secretToken       = 'yourSecretToken';
$queryString       = $request->getUri()->getQuery();
$iAdvizeSignature  = $headers['X-iAdvize-Signature'];

// Get alogrithm and hash
list($algorithm, $iAdvizeHash) = explode('=', $iAdvizeSignature, 2);
 
// Computed hash with query parameters
$queryParametersHash = hash_hmac($algorithm, $queryString, $secretToken);
 
// Final check
if (! hash_equals($iAdvizeHash, $queryParametersHash)) {
    exit('Validation hash failed');
}

We strongly recommend you, to use the constant time string comparison method (hash_equals vs === in our example), to be less vulnerable to timing attacks.

Developer Policy

Developers host their code on their own host service. Developers are responsible for their connector's maintenance. Developers can set their app’s price (monthly fee per user). If it’s not a free app, developers must be a legal person.

REST API

Current version: 2.0

This API provides access and basic CRUD operations (create, read, update, delete) for the resources described in the documentation. The REST API uses JSON exclusively. XML is not supported.

Base URL

All URLs referenced in the documentation have the following base:

Standard platformHigh availability platform
https://www.iadvize.com/api/2https://ha.iadvize.com/api/2

The iAdvize REST API is served over HTTPS.

Authentication

The API key must be attached to each request. You can use it in one of the following ways:

  • Passed in as a X-API-Key HTTP header
  • Passed in as a key GET parameter
  • Passed in as the username (with an arbitrary password) via HTTP Basic authentication

Calls, errors & responses

Authentication failed

{
  meta: {
    status: "error",
    message: "Forbidden"
  }
}

Create

POST /my_resource my_field=my_value
{
  meta: {
    status: "success"
  },
  data: {
    id: 123,
    my_field: "my_value",
    _link: "/my_resource/123"
  }
}
POST /my_resource my_field=my_value (with error)
{
  meta: {
    status: "fail",
    message: "Field 'my_field_2' is missing.",
  }
}

Read

GET /my_resource
{
  meta: {
    status: "success"
  },
  data: [
    {
      id: 789,
      _link: "/my_resource/789"
    },
    {
      id: 456,
      _link: "/my_resource/456"
    },
    {
      id: 123,
      _link: "/my_resource/123"
    }
  ],
  pagination: {
    page: 1,
    pages: 1,
    limit: 20,
    count: 3
  }
}

Common filters

FilterDescriptionValues
pagePage number?page=1
limitMaximum number of resources per page (maximum possible value is 100)?limit=1
fullShow all fields of the resource?full=1

Use the * character to broaden the scope of your search. E.g.: filters[name]=*uli*

GET /my_resource/123
{
  meta: {
    status: "success"
  },
  data: {
    id: 123,
    my_field: "my_value",
    _link: "/my_resource/123"
  }
}
GET /my_resource/456 (with error)
{
  meta: {
    status: "fail",
    message: "Unknown 'my_resource' with 'id' 456."
  }
}

Update

PUT /my_resource/123 my_field=my_new_value
{
  meta: {
    status: "success"
  },
  data: {
    id: 123,
    my_field: "my_new_value",
    _link: "/my_resource/123"
  }
}
PUT /my_resource/123 my_field=my_value (with error)
{
  meta: {
    status: "fail",
    message: "Value of field 'my_field' is not valid."
  }
}

Delete

DELETE /my_resource/123
{
  meta: {
    status: "success"
  }
}

DELETE /my_resource/456 (with error)

{
  meta: {
    status: "fail"
    message: "Unknown 'my_resource' with 'id' 456"
  }
}

Resources

Client

List all clients

GET /client

See below to discover used fields and see reading section to discover some output examples.

This list is displayed depending on the rights of your API key.

Showing client

GET /client/1

See reading section to discover some output examples.

Fields

FieldDescriptionValues
idIdentifierInteger
langLanguageString (2 chars)

Website

List all your websites

GET /website

See below to discover used fields and see reading section to discover some output examples.

Get a website details

GET /website/1

See reading section to discover some output examples.

Fields

FieldDescriptionValues
idIdentifierInteger
urlURLString
labelLabelString
client_idClient identifierInteger

Update a website

PUT /website/1

See updating section to discover some output examples.

Operator

List your operators

GET /operator

See below to discover used fields and see reading section to discover some output examples.

Filters

FilterDescriptionValuesUse
idOperator identifier?filters[id]=123
group_idGroup identifier?filters[group_id]=123
website_idWebsite identifier?filters[website_id]=123
skill_idSkill identifier?filters[skill_id]=123
nameOperator name?filters[name]=genius
external_idExternal identifier?filters[external_id]=MyExternalId
connectedOperator online status0 (offline) or 1 (online)?filters[connected]=1

Get operator's details

GET /operator/1

See reading section to discover some output examples.

Fields

FieldDescriptionValues
idOperator identifierInteger
nameNameString
first_nameFirst nameString
pseudoPseudonymString
emailEmailValid email
external_idYour id if providedString
role deprecated, use roles property insteadRoleoperator, manager or admin
rolesRolesList of string expert, operator, manager or admin
chat_enabledAbility to process chatBoolean
call_enabledAbility to process callBoolean
video_enabledAbility to process videoBoolean
chat_max_numberMax. amount of chats an operator can process at the same timeInteger
chat_and_callAbility to process chat and call simultaneouslyBoolean
chat_priorityChat priority of the operator0 or 10
call_priorityCall priority of the operator0 or 10
video_priorityVideo priority of the operator0 or 10
language_listList of languages the operator can processList of ISO2 (e.g. en, fr...)
language_adminAdmin languagede, en, es or fr
group_idGroup identifierInteger
website_listWebsite list identifiersList of integer
skill_listSkill list identifiersList of integer
sso_keySSO tokenString

Create an operator

POST /operator

See creating section to discover some output examples.

Update an operator

PUT /operator/1

See updating section to discover some output examples.

Delete an operator

DELETE /operator/1

See deleting section to discover some output examples.

Get operators live availability

Get the live availability of all of your operators.

GET /operator/live

{
  meta: {
    status: "success"
  },
  data: [
    {
      id: 456,
      connected: true,
      chat: {
        enabled: true,
        slot_number: 2,
        slot_max_number: 4,
        busy: false,
        available: true
      },
      call: {
        enabled: false,
        slot_number: 0,
        slot_max_number: 1,
        busy: false,
        available: false
      },
      video: {
        enabled: false,
        slot_number: 0,
        slot_max_number: 1,
        busy: false,
        available: false
      }
    }
  ]
}

You can use previous filters.

  • In order to have more accurate results, only available operators are displayed in the default view.
  • If you want to display offline operators, we invite you to use the connected filter. Please note that you will only see agents that logged in to the iAdvize platform at least once.
  • If your operators have skills or groups, you need to specify it in your request.

Get operator's live availability

Get the live availability of an operator.

GET /operator/123/live

{
  meta: {
    status: "success"
  },
  data: {
    id: 123,
    connected: false,
    chat: {
      enabled: false,
      slot_number: 1,
      slot_max_number: 2,
      busy: false,
      available: false
    },
    call: {
      enabled: true,
      slot_number: 1,
      slot_max_number: 1,
      busy: true,
      available: false
    },
    video: {
      enabled: false,
      slot_number: 0,
      slot_max_number: 1,
      busy: false,
      available: false
    }
  }
}

Set operator's availability

Set the availability of an operator.

PUT /operator/123/live

Fields

FieldDescriptionValue
chat[available]Set operator availability for chat channel1 (available) or 0 (unavailable)
call[available]Set operator availability for call channel1 (available) or 0 (unavailable)
video[available]Set operator availability for video channel1 (available) or 0 (unavailable)
connectedSet operator connection status0 (offline) - unique value possible

Response

{
  meta: {
    status: "success",
    message: "Operator is now available|unavailable for chat channel."
  }
}

Get operators statistics

GET /operator/123/statistic

See reading section to discover some output examples.

Fields

FieldDescriptionValues
idOperator identifierInteger
conversation_numberConversations number done by operatorInteger
satisfaction_global_rateSatisfaction average for operator conversationsFloat
experienceOperator experienceInteger

Response

{
  meta: {
    status: "success"
  },
  data: {
    id: 123,
    conversation_number: 589,
    satisfaction_global_rate: 0.86,
    experience: 5630
  }
}

Get operator's profile

GET /operator/123/profile

See reading section to discover some output examples.

Fields

FieldDescriptionValues
user_idOperator identifierInteger
statusShort text status written by operatorString
descriptionOperator profile descriptionString
facebookFacebook identifierString
twitterTwitter identifierString
cityCityString
countryCountryString
Response
{
  meta: {
    status: "success"
  },
  data: {
    user_id: 123,
    status: "Je suis disponible pour vous aider",
    description: "Passionné par la menuiserie depuis plusieurs années, j'aime vous apporter des conseils.",
    facebook: "john.doe",
    twitter: "johndoe45",
    city: "Nantes",
    country: "France"
  }
}

Group

List your groups

GET /group

See below to discover used fields and see reading section to discover some output examples.

Filters

FilterDescriptionUse
parent_idParent group identifier?filters[parent_id]=1987

Get a group details

GET /group/1984

See reading section to discover some output examples.

Fields

FieldDescriptionValues
idGroup identifierInteger
nameGroup nameString
created_atDate of creationDate YYYY-MM-DD HH:MM:SS
parent_idParent identifierInteger
operator_listList of operators identifiersList of integers
parent_listList of parent's group idsList of integers

Create a group

POST /group

See creating section to discover some output examples.

Update a group

PUT /group/1

See updating section to discover some output examples.

Delete a group

DELETE /group/1

See deleting section to discover some output examples.

Skill

List your skills

GET /skill

See below to discover used fields and see reading section to discover some output examples.

Filters

FilterDescriptionUse
operator_idOperator identifier?filters[operator_id]=123
parent_idParent skill identifier?filters[parent_id]=123

Get a skill details

GET /skill/1984

See reading section to discover some output examples.

Fields

FieldDescriptionValues
idSkill identifierInteger
nameNameString
orderOrderInteger
created_atDate of creationDate YYYY-MM-DD HH:MM:SS
parent_idParent skill identifierInteger
operator_listdeprecated, use the Operator resource with the skill_id filter insteadList of operator identifiersList of integers

Create a skill

POST /skill

See creating section to discover some output examples.

Update a skill

PUT /skill/1

See updating section to discover some output examples.

Delete a skill

DELETE /skill/1

See deleting section to discover some output examples.

Conversation

List your conversations

GET /conversation.json-unicode?formatHistory=0

See below to discover used fields and see reading section to discover some output examples. Don't forget to use json-unicode path parameter & formatHistory query parameter to retrieve a well formatted conversation history.

Filters

FilterDescriptionValuesUse
channelChannelchat, call, video or social?filters[channel]=chat
fromDate from (see more information below)YYYY-MM-DD or YYYY-MM-DD HH:MM:SS?filters[from]=2013-08-22
toDate to (see more information below)YYYY-MM-DD or YYYY-MM-DD HH:MM:SS?filters[to]=2013-08-25
website_idWebsite identifier?filters[website_id]=123
operator_idOperator identifier?filters[operator_id]=123
visitor_idVisitor identifier?filters[visitor_id]=123
skill_idSkill identifier?filters[skill_id]=123
tag_idTag identifier?filters[tag_id]=123
rule_idRule identifier?filters[rule_id]=123

A request cannot fetch the conversations for a period over 3 months. The following rules apply :

  • If from and to are not specified, the last 3 months are fetched
  • If from is specified but not to, the 3 months after from are fetched
  • If to is specified but not from, the 3 months before to are fetched
  • If from and to are specified but with an interval over 3 months, an error is returned in the meta attribute of the response

Get a conversation details

GET /conversation.json-unicode/666?formatHistory=0

See reading section to discover some output examples. Don't forget to use json-unicode path parameter & formatHistory query parameter to retrieve a well formatted conversation history.

Fields

FieldDescriptionValues
idConversation identifierInteger
channelConversation channelchat, call or video
visitor_uidVisitor unique identifierString
historyConversation historyString (see the different types of messages in the table below ‘Conversation history details‘)
operator_answerConversation answered by operatorBoolean
operator_closedConversation closed by operatorBoolean
waitinglistWaiting list statusBoolean
page_typePage typeString
created_atConversation start timeDate YYYY-MM-DD HH:MM:SS
closed_atConversation end timeDate YYYY-MM-DD HH:MM:SS
website_idWebsite identifierInteger
operator_idOperator identifierInteger
skill_idSkill identifierInteger
tag_listList of tag identifiersList of integers
rule_idRule identifierInteger
xmpp_idXMPP related identifierUUID

Conversation history details You can retrieve different types of messages into the conversation.

FieldDescriptionValues
historyText message sent by Operator[1,"2016-02-16 11:24:43","Hello, how can I help you?",1455618283869],
historyText message sent by Visitor[2,"2016-02-16 11:25:26","I would like to know if my order: xxx has been sent",1455618327321],
historySoftware notifications[3,"2016-02-16 11:24:31","The chat rule has been activated."], [3,"2016-02-16 11:26:43","OPERATOR_CHAT_CLOSE"]
historyURL - Link[5,"2016-02-16 11:24:21","http://iadvize.com/"]
historyRich content sent by Operator[6,"2016-02-16 11:24:21","http://img.png/"]
historyRich content sent by Visitor[7,"2016-02-16 11:24:21","http://img.png/"]

Conversation history types example

{
  [5,"2016-02-16 11:24:21","http://test.com/"],
  [2,"2016-02-16 11:24:23","Hello",1455618264049],
  [3,"2016-02-16 11:24:31","The chat rule has been activated."],
  [1,"2016-02-16 11:24:43","Hello, how can I help you?",1455618283869],
  [2,"2016-02-16 11:25:26","I would like to know if my order: xxx has been sent",1455618327321],
  [1,"2016-02-16 11:25:45","I check it, thank you for your patience",1455618346030],
  [1,"2016-02-16 11:26:02","Your order has been shipped",1455618363054],
  [2,"2016-02-16 11:26:09","Thanks, goodbye",1455618370072],
  [1,"2016-02-16 11:26:17","Goodbye",1455618377364],
  [3,"2016-02-16 11:26:43","OPERATOR_CHAT_CLOSE"]`
}

Tag

List your tags

GET /tag

See below to discover used fields and see reading section to discover some output examples.

Filters

FilterDescriptionUse
website_idWebsite identifier?filters[website_id]=123

Get a tag details

GET /tag/123

See reading section to discover some output examples.

Fields

FieldDescriptionValues
idTag identifierInteger
nameNameString
website_idList of website identifiersList of integers

Create tag(s)

POST /tag

Parameters (send an array of object as application/json)

FieldDescriptionValuesMandatory
nameNameStringYes
website_idwebsite identifierIntegerYes

Response

{
    meta: {
        status: "success"
    },
    data: [
        {
            id: 123,
            name: "my_value",
            website_id: 1,
            _link: "/tag/123"
        },
        {
            id: 124,
            name: "my_value_2",
            website_id: 1,
            _link: "/tag/124"
        }
    ]
}

Transaction

List your transactions

GET /transaction

See below to discover used fields and see reading section to discover some output examples.

Filters

FilterDescriptionValuesUse
website_idWebsite identifier?filters[website_id]=123
operator_idOperator identifier?filters[operator_id]=123
conversation_idConversation identifierConversation identifier. You can also use !null & null to filter all transactions associated or not to a conversation.?filters[conversation_id]=123 ?filters[conversation_id]=null ?filters[conversation_id]=!null
fromDate fromYYYY-MM-DD or YYYY-MM-DD HH:MM:SS?filters[from]=YYYY-MM-DD HH:MM:SS
toDate toYYYY-MM-DD or YYYY-MM-DD HH:MM:SS?filters[to]=YYYY-MM-DD HH:MM:SS

Get a transaction details

GET /transaction/123

See reading section to discover some output examples.

Fields

FieldDescriptionValues
idTag identifierInteger
external_idExternal identifierString
visitor_uidVisitor unique identifierString
visitor_emailVisitor emailString
amountAmountDouble
created_atDate of creationDate YYYY-MM-DD HH:MM:SS
website_idWebsite identifierInteger
operator_idOperator identifierInteger
conversation_idConversation identifierInteger

Satisfaction

List your satisfactions

GET /satisfaction

See below to discover used fields and see reading section to discover some output examples.

Filters

FilterDescriptionValuesUse
website_idWebsite identifier?filters[website_id]=123
operator_idOperator identifier?filters[operator_id]=123
conversation_idConversation identifier?filters[conversation_id]=123
fromDate fromYYYY-MM-DD or YYYY-MM-DD HH:MM:SS?filters[from]=YYYY-MM-DD HH:MM:SS
toDate toYYYY-MM-DD or YYYY-MM-DD HH:MM:SS?filters[to]=YYYY-MM-DD HH:MM:SS

Get a satisfaction details

GET /satisfaction/123

See reading section to discover some output examples.

Fields

FieldDescriptionValues
idSatisfaction identifierInteger
note_welcomeWelcome noteDouble (percentage)
note_resolutionResolution noteDouble (percentage)
node_delayDelay noteDouble (percentage)
created_atDate of creationDate YYYY-MM-DD HH:MM:SS
website_idWebsite identifierInteger
operator_idOperator identifierInteger
conversation_idConversation identifierInteger

Statistic

Get statistics

GET /statistic

See below to discover used fields and see reading section to discover some output examples.

Filters

FilterDescriptionValuesUse
website_id deprecated, use website_list property insteadWebsite identifier?filters[website_id]=123
website_listWebsite identifiers?filters[website_list]=123,24,32
channelChannelchat, call, facebook, twitter, facebookBusinessOnMessenger, instagram, sms, whatsapp or video?filters[channel]=chat
resourceResource to group the data byoperator, group, skill, rule, contact_type or page_type?filters[resource]=operator
resource_idResource ID to get only the data of this resource?filters[resource_id]=32
indicatorsIndicators to filterSee list below?filters[indicators]=indicator1,indicator2
fromDate fromYYYY-MM-DD or YYYY-MM-DD HH:MM:SS?filters[from]=YYYY-MM-DD
toDate toYYYY-MM-DD or YYYY-MM-DD HH:MM:SS?filters[to]=YYYY-MM-DD
granularityGet data per hour, per day or per month (only when 1 indicator is requested)hour, day, month?filters[indicators]=indicator1&filters[granularity]=day

Indicators

Contact indicators

available on chat, call, video, facebook, twitter, facebookBusinessOnMessenger, sms, whatsapp
IndicatorLabelDescriptionValue
contact_answered_after_first_message_durationResponse time after first messageAverage response time between a customer's first question and the agent's answer.Second
contact_answered_durationResponse timeAverage response time between a customer's request and the agent's response.Second
contact_closed_after_last_message_durationLength of time between last message and closing of chatAverage amount of time between the visitor's last message and the closing of the chat discussion on the panel.Second
contact_durationAverage processing timeAverage length of all contacts, the length of a contact being defined as the difference between the end time (closure) and start time.Second
contact_numberInitiated contactsNumber of contacts initiated during the selected period.Number
contact_sent_message_numberSent messagesTotal number of messages within a conversation sent by the agents.Number
contact_received_message_numberReceived messagesTotal number of messages within a conversation received by the agents.Number
contact_unanswered_numberContacts initiated with no responseNumber of contacts initiated by a visitor with no response from an agent.Number
available on chat
IndicatorLabelDescriptionValue
contact_missed_numberMissed contact opportunitiesEstimated number of missed contact opportunities because the agents were totally busy, offline or not in production.Number
contact_missed_with_busy_operators_numberMissed contact opportunities (agents busy)Estimated number of missed contact opportunities due to agents being totally busy.Number
contact_missed_with_no_operators_numberMissed contact opportunities (agents absent)Estimated number of contacts missed because the agents were either not connected or not in production.Number
contact_simultaneous_numberSimultaneous contactsAverage number of contacts processed simultaneously by an agent during his online presence.Number
available on chat, and video
IndicatorLabelDescriptionValue
contact_waiting_abort_numberAbandoned contactsNumber of contacts initiated in the queue who left before being processed.Number
contact_waiting_answered_numberProcessed contactsNumber of processed contacts coming from the queue.Number
contact_waiting_before_quit_durationWaiting time before abandonmentAverage time before a visitor abandons the queue.Second
contact_waiting_durationWaiting time before contactAverage waiting time of visitors in the queue.Second
contact_waiting_numberInitiated contactsAverage waiting time of visitors in the queue.Number
available on chat, call, video
IndicatorLabelDescriptionValue
contact_per_hour_average_numberContacts / hr of the websiteAverage number of contacts processed by all agents for an hour of production.Number
contact_per_hour_numberContacts per hourAverage number of contacts processed by an agent for an hour of production.Number
rule_contact_rateResponse rateProportion of displays having generated a contact.Rate
rule_display_numberDisplaysNumber of chat/call displays generated on the website during the period.Number
targeting_rule_triggeredTriggersNumber of times a targeting rule has been triggered, as a consequence of visitors meeting the right criteria.Number

Presence indicators

available on chat, call and video
IndicatorLabelDescriptionNumber
max_and_partial_occupation_durationGlobal occupationPeriod during which an agent is connected to the panel and is occupied partially or to the maximum.Second
max_occupation_durationMaximum occupationPeriod during which an agent is connected to the panel and is occupied to maximum capacity.Second
max_occupation_rateMaximum occupation ratePart of production time during which an agent is connected to the panel and is occupied to a maximum.Rate
non_production_durationNot in productionPeriod during which an agent is connected to the panel, unavailable and yet not busy.Second
non_production_rateNot in production rateProportion of connection time during which an agent is connected to the panel, unavailable and yet not busy.Rate
presentation_durationSmoothed period of button presentationPeriod during which buttons are displayable. Length of the time slot covered with at least one agent available.Second
production_smoothed_durationSmoothed period of productionPeriod during which operators were in production. Length of the time slot covered with at least one agent in production.Second
available on chat, call, video, facebook, twitter facebookBusinessOnMessenger, sms, whatsapp
IndicatorLabelDescriptionValue
presence_durationTotal period of presenceTotal period during which the agents were connected to the desk.
presence_smoothed_durationSmoothed period of presencePeriod during which operators were connected. Length of the time slot covered with at least one agent present.
occupation_ratePartial occupation ratePart of production time during which an agent is connected to the panel and is partially busy.
non_occupation_durationInocc.Period of time during which an agent is connected to the panel and is simultaneously available and not busy.
non_occupation_rateRate of non-occupationPart of production time during which an agent is connected to the panel and is simultaneously available and not busy.
max_and_partial_occupation_rateGlobal occupation ratePart of production time during which an agent is connected to the panel and is occupied partially or to the maximum.
production_durationIn productionPeriod during which an agent is connected to the panel and is available or busy.

Satisfaction indicators

available on chat, call and video
IndicatorLabelDescriptionValue
satisfaction_delay_rateWaiting timeVisitor satisfaction rate with the waiting time before receiving an answer.Rate
satisfaction_global_rateOverall satisfactionOverall satisfaction rate of visitors.Rate
satisfaction_resolution_rateQuality of responseVisitors' satisfaction rate with the response given by the agent.Rate
satisfaction_respondent_numberNumber of respondentsNumber of visitors who replied to a satisfaction survey following a discussion.Number
satisfaction_respondent_rateResponse rateProportion of conversations after which visitors completed the satisfaction survey.Rate
satisfaction_welcome_rateQuality of welcomeVisitor satisfaction rate with the welcome.Rate
occupation_durationPartial occupationPeriod during which an agent is connected to the panel, unavailable and yet not busy.Second

Transactions indicators

available on chat, call, video, facebook, twitter, facebookBusinessOnMessenger, sms, whatsapp
IndicatorLabelDescriptionValue
conversion_rateConversion rateProportion of conversations which led to transactions.Rate
cart_after_contact_amountAverage order value after contactAverage order value following a contact.Number
cart_global_amountAverage order value on the websiteAverage Order Value, all visitor categories.Amount
transaction_after_contact_amountT/O after contactTotal turnover from visitors who dialogued and completed a transaction after a contact.Amount
transaction_after_contact_numberTransactions after contactTotal number of transactions from visitors who dialogued and then completed a transaction following the contact.Number
transaction_total_amountWebsite T/OTotal turnover, all visitor categories.Amount
transaction_total_numberWebsite transactionsTotal number of transactions (all categories).Number
transaction_after_contact_durationTransformation time after contactAverage time between the first exchange and the transaction following a contact.Second
transaction_after_conversation_amount_per_hourWebsite transactions amount per hourAverage turnover generated by an agent after a contact on an hourly basisAmount
transaction_missed_with_busy_operators_amountT/O missed (agents totally busy)Estimated lost turnover due to agents being totally busy.Amount
transaction_missed_with_busy_operators_numberMissed transaction opportunities (agents totally busy)Estimated number of missed transaction opportunities because the agents were totally busy.Number
transaction_missed_with_no_operators_amountMissed T/O opportunity (agents absent)Estimated turnover missed because the agents were not connected or not in production.Amount
transaction_missed_with_no_operators_numberMissed transaction opportunities (agents absent)Estimated number of missed transaction opportunities because the agents were not connected or not in production.Number
transaction_amount_per_conversationWebsite transactions amount per conversationAverage turnover generated for each conversation doneAmount

Visitor

Get visitors

GET /visitor

See below to discover used fields and see reading section to discover some output examples.

Filters

FilterDescriptionUse
unique_idUnique identifier?filters[unique_id]=123
external_idExternal identifier?filters[external_id]=123
website_idWebsite identifier?filters[website_id]=123

Get a visitor details

GET /visitor/560

See reading section to discover some output examples.

Fields

FieldDescriptionValues
idVisitor identifierInteger
unique_idVisitor unique identifierString
external_idYour id if providedString
lastnameLast nameString
firstnameFirst nameString
addressAddressString
cityCityString
zipZip codeString
countryCountryString
phonePhone numberString
emailEmailString
browserBrowser used by visitorString
website_idList of website identifiersList of integers
created_atVisitor creation dateDate YYYY-MM-DD HH:MM:SS

Create a visitor

POST /visitor

See creating section to discover some output examples.

Update a visitor

PUT /visitor/560

See updating section to discover some output examples.

Delete a visitor

DELETE /visitor/560

See deleting section to discover some output examples.

Call meeting

Get call meetings

GET /callmeeting

See below to discover used fields and see reading section to discover some output examples.

Filters

FilterDescriptionUse
website_idWebsite identifier?filters[website_id]=123
fromPeriod start date?filters[from]=2015-03-31 19:00:00
toPeriod end date?filters[to]=2015-06-31 18:00:00

Fields

FieldDescriptionValues
idCall meeting identifierInteger
phone_numberVisitor phone numberString
visitor_uidVisitor unique identifierString
statusCall meeting status (pending, progress, done, failed, working)String
start_atDate of callDateTime
website_idWebsite identifierInteger
targeting_rule_idTargeting rule identifier associated to call meetingString
skill_idSkill identifier associated to call meetingString

Callback Odigo

Pick up callback

POST /odigocallback/pickup

Parameters (sent as application/x-www-form-urlencoded)

ParameterDescriptionValuesMandatory
operator_external_idOperator external identifierStringYes
website_idWebsite identifierIntegerYes
phone_numberVisitor phone numberStringYes

Response

{
    meta: {
        status: "success"
    },
    data: {
        targeting_rule_id: 107,
        website_id: 1,
        conversation_id: 139,
        skill_id: null,
        visitor_phone_number: "0614037735",
        visitor_uid: "0a1572b7cc5027fe443f4203eaf0b98d4cbea6d313afa"
    }
}

Hang up callback

POST /odigocallback/hangup Parameters (sent as application/x-www-form-urlencoded)

ParameterDescriptionValuesMandatory
operator_external_idOperator external identifierStringYes
website_idWebsite identifierIntegerYes
phone_numberVisitor phone numberStringYes

Response

{
  meta: {
    status: "success"
  },
  data: []
}

GraphQL API alpha

Getting started on GraphQL

GraphQL is our new API, all new resources will only be exposed in this new API. We are currently migrating old resources from Rest API to GraphQL. Please note that we are in alpha version, resources are pretty stable but authentication method will change in the next months.

One of the power of GraphQL API is to allow you retrieve many resources in one HTTP call. You can request only fields you need. If you wan to learn more about GraphQL, please check Learn GraphQL

Authentication

Authentication uses temporary & revocable access tokens. You can generate an access token by calling the url below with a user email & password.

POST /oauth2/token Parameters (sent as application/x-www-form-urlencoded)

ParameterDescriptionValuesMandatory
usernameUser emailStringYes
passwordUser passwordStringYes
grant_typeOauth2 grant type (only password is supported)StringYes
{
    "refresh_token": "***************************",
    "token_type": "bearer",
    "expires_in": 86400,
    "access_token": "***************************"
}
    curl -XPOST https://api.iadvize.com/oauth2/token -d "username={EMAIL}&password={PASSWORD}&grant_type=password"

To authenticate an API call just pass the access token in an authorization header. You can verify token validity with the authenticated route below.

    curl -H "Authorization: Bearer {ACCESS_TOKEN}" https://api.iadvize.com/_authenticated

Resources

Documentation GraphQL

Example

To use the GraphQL API, call the URL below with the Authorization header containing your access token.

POST /graphql Parameters (sent as application/json)

ParameterDescriptionValuesMandatory
queryGraphQL queryStringYes
variablesVariables to be used in the GraphQL queryStringNo
operationNameOperation to perform if the GraphQL query contains several operationsStringNo

For example:

{
  "query": "query GetConnector($connectorId: UUID!) { connector(id: $connectorId) { name } }",
  "variables": {
    "connectorId": "41c64064-4729-4d83-a939-8d46ac06d207"
  }
}

Result:

{
  "data": {
    "connector": {
      "name": "..."
    }
  }
}

Webhooks

Events description

DomainNameDescription
conversations.domainconversation.startedChat or call conversation
conversations.domainconversation.closedChat or call conversation
conversations.domainconversation.transferredChat conversation
conversations.domainvisitor.updatedVisitor information updated from desk or admin view
users.domainuser.createdUser created
users.domainuser.updatedUser information updated
users.domainsatisfaction.filled
users.domainuser.connected
users.domainuser.disconnected

Payloads

When an event occurs, an HTTP POST call is issued on the callback urls you set up with the event data. Data is sent with “application/json” header content-type, and “json” format as payload. Callback urls must be defined with HTTPS protocol and should be available with POST verb to send data payload. iAdvize expect to have à 20x http status in callback result.

Output examples of Conversations domain:

Please note :

AttributDescription
clientIdAs a client of iAdvize you have a specific ID, it is what this one represents
visitorIdEach visitor has a unique ID. iAdvize calls it visitor unique ID

conversation.started

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "conversation.started",
    "platform": "sd",
    "websiteId": 1,
    "clientId": 1,
    "conversationId": 1,
    "operatorId": 1,
    "channel": "chat",
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

conversation.closed

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "conversation.closed",
    "platform": "sd",
    "websiteId": 1,
    "clientId": 1,
    "conversationId": 1,
    "operatorId": 1,
    "channel": "chat",
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

conversation.transferred

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "conversation.transferred",
    "platform": "sd",
    "websiteId": 1,
    "clientId": 1,
    "conversationId": 2,
    "transferredConversationId": 1,
    "operatorId": 1,
    "channel": "chat",
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

user.created

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "user.created",
    "platform": "sd",
    "clientId": 1,
    "userId": 1,
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

user.updated

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "user.updated",
    "platform": "sd",
    "clientId": 1,
    "userId": 1,
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

visitor.updated

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "visitor.updated",
    "platform": "sd",
    "clientId": 1,
    "operatorId": 1,
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

satisfaction.filled

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "satisfaction.filled",
    "platform": "sd",
    "websiteId": 1,
    "clientId": 1,
    "conversationId": 1,
    "operatorId": 2,
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "score": 3,
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}
HTTP stack trace example for “conversation.closed” event

POST /webhook HTTP/1.1

Host: localhost
X-iAdvize-Signature: sha256=110e8400-e29b-11d4-a716-446655440000
X-iAdvize-CorrelationId: 332e8400-e34b-11d4-a716-446655444444
X-iAdvize-Delivery: 110e8400-e29b-11d4-a716-446655440000
Content-Type: application/json
Content-Length: 3442

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "conversation.closed",
    "platform": "sd",
    "websiteId": 1,
    "clientId": 1,
    "conversationId": 1,
    "operatorId": 1,
    "channel": "chat",
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

Delivery headers

iAdvize will send payload with three additional headers:

  • X-iAdvize-Delivery: UUID, unique identifier to describe this webhook delivery
  • X-iAdvize-CorrelationId: UUID, event identifier used in retry webhooks to track same callback calls.
  • X-iAdvize-Signature: Hash signature, cf. Security section

Webhook retry management

If errors occur during webhook query (40x, 50x http status codes), we will retry two times. We will try to send you the following requests:

  • First time after delay of 10 seconds,
  • and second time after 20 seconds (so, 30 seconds after first call).

In case of failure, you may need to track events in error, by following "X-iAdvize-CorrelationId" in headers, or "eventId" in payload.

Webhook security

For security reasons iAdvize provides you with a method to verify and secure your Webhooks notifications. You will be able to make sure that the payloads have not been subjected to modifications, and to verify its source in order for example to limit the requests to those coming from iAdvize.

Once your server is configured to receive payloads, you can set up a secret token and verify the information.

Set you secret token

First, you need to get one or several secret token depending on your project.

If you build a connector thanks to our Developer Platform, you will have to use one token per connector (no matters the number of webhook you set within your connector). You can retrieve this token in the 'App information' section.

If you want to use the webhook system without building a connector, you will have to use one token per webhook. To retrieve the token(s) you must contact us at developers@iadvize.com and we will generate the token for you.

Validating payloads from iAdvize

Once the secret token set, iAdvize will create a hash signature. This hash signature is passed along with each request in the headers as X-iAdvize-Signature. Hash signature starts with algorithm name sha256= and is computed by hashing body payload with HMAC hexdigest algorithm and your secret token as salt.

X-iAdvize-Signature: sha256=110e8400-e29b-11d4-a716-446655440000

You have to compute a new hash using your secret token, and to compare it with X-iAdvize-Signature and make sure it matches. Here is an example of a PHP implementation:

$secretToken       = 'yourSecretToken';
$headers           = getallheaders();
$iAdvizeSignature  = $headers['X-iAdvize-Signature'];

// Get alogrithm and hash
list($algorithm, $iAdvizeHash) = explode('=', $iAdvizeSignature, 2);
 
// Get body payload from webhook
$bodyPayload = file_get_contents('php://input');
 
// Computed hash with body payload
$bodyPayloadHash = hash_hmac($algorithm, $bodyPayload, $secretToken);
 
// Final check
if (! hash_equals($iAdvizeHash, $bodyPayloadHash)) {
    exit('Validation hash failed');
}

We strongly recommend you, to use the constant time string comparison method (hash_equals vs === in our example), to be less vulnerable to timing attacks.

Push API (deprecated)

The iAdvize Push API will be deprecated starting september, 2017. The Push API will stop working from january 30th, 2018. From now, we recommend to use our webhooks system. The Push API allows data to be pushed to URI callbacks when an event is fired.
The Push API uses JSON exclusively. XML is not supported. Push requests are sent with a POST method.

Events

operator.login

When an operator connects to the desk.

Returned data

{
    "name": "operator.login",
    "datetime": {
        "created": "2014-01-01 00:00:00",
        "sent": "2014-01-01 00:00:01"
    },
    "parameters": {
        "operator_id": 1
    }
}

operator.logout

When an operator disconnects from the desk.

Returned data

{
    "name": "operator.logout",
    "datetime": {
        "created": "2014-01-01 00:00:00",
        "sent": "2014-01-01 00:00:01"
    },
    "parameters": {
        "operator_id": 1
    }
}

conversation.start

When a conversation is started.

Returned data

{
    "name": "conversation.start",
    "datetime": {
        "created": "2014-01-01 00:00:00",
        "sent": "2014-01-01 00:00:01"
    },
    "parameters": {
        "conversation_id": 1,
        "type":            "chat|call|video",
        "operator_id":     1,
        "website_id":      1,
        "group_id":        1,
        "custom_data":     {
            "example":     "value"
        }
    }
}

conversation.end

When a conversation is ended by the operator.

Returned data

 {
    "name": "conversation.end",
    "datetime": {
        "created": "2014-01-01 00:00:00",
        "sent": "2014-01-01 00:00:01"
    },
    "parameters": {
        "conversation_id": 1,
        "type":            "chat|call|video",
        "operator_id":     1,
        "website_id":      1,
        "group_id":        1
    }
}

Single Sign On

iAdvize offers a Single Sign On method that allows you to provide a unique authentication system to your operators who are already logged to your app.

Benefits

If your users have to switch between several apps (including iAdvize) during their daily work, Single Sign On method has some interesting benefits :

  • Reducing password fatigue from different user name and password combinations
  • Reducing time spent re-entering passwords for the same identity
  • Reducing IT costs due to lower number of IT help desk calls about passwords

Implementation

To connect an operator to its iAdvize console :

That's all! When a user visit the URL, he will be automatically logged to its iAdvize account and no login / password will be asked to him.

Use specific links

It's possible to use a specific link with a parameter called dest to go to a specific page.

Examples below:

PageURL
Discussion panelhttps://www.iadvize.com/admin/login?key={SSO_KEY}&dest=/pupitre
Usershttps://www.iadvize.com/admin/login?key={SSO_KEY}&dest=/admin/users

To find the parameter dest that interest you, look the URL address of the page in your favorite web browser.

URL example

With this example, the SSO URL address will be: https://www.iadvize.com/admin/login?key={SSO_KEY}&dest=/admin/users/