Conversation flow

Method	Endpoint	Description
GET	/bots/:operatorId/conversation-first-messages	to return the first messages you want to send as soon as the visitor opens up the chatbox (before the conversation really starts)
POST	/conversations/	to handle the conversation creation
POST	/conversations/:conversationId/messages	to receive and reply to messages from visitors. Mind that all the messages posted in a conversation will result into this API call (which means you will also receive your own replies).

Please note that all endpoints are subject to a 10 seconds timeout except for GET /bots/:operatorId/conversation-first-messages which has a 2 seconds timeout.

How it works?

A conversation is typically initiated by a visitor. The bot can reply to user’s message, which means that iAdvize will call your endpoints when a message is received in the conversation.

Conversation flow diagram

Here is a full conversation example:

Time	Bot Agent	Visitor		Bot response	Calls to bot connector	Explanation
00:00		“Hi, are you there ? Shall we begin ?”	⟹		POST /conversations	Create a conversation in the bot connector
			⟸	(empty replies)	Response
00:00			⟹		POST /conversations/:conversationId/messages “Hi, are you there ? Shall we begin ?”	Reply to the first user’s message
			⟸ ⟸ ⟸	Await 5s “How are you ?” “Fine” or “Bad” Await 3 minutes “Are you there ?”	Response
00:05	“How are you ? ”		⟹		POST /conversations/:conversationId/messages “How are you ?”	Do not reply to your own scheduled message (filter on author operator)
			⟸ ⟸	(empty replies)	Response
🕐
03:05	“Are you there ?”		⟹		POST /conversations/:conversationId/messages “Are you there ?”	Do not reply to your own scheduled message
			⟸	(empty replies)	Response
03:12		“Yes I'm here, sorry"	⟹		POST /conversations/:conversationId/messages “Yes I’m here, sorry ?”	Reply to the user’s message by repeating the question
			⟸	Await 1s “How are you ?” “Fine” or “Bad”	Response
03:13	“How are you ?”		⟹		POST /conversations/:conversationId/messages “How are you ?”	Do not reply to your own message
			⟸	(empty replies)	Response
03:42		“Good”	⟹		POST /conversations/:conversationId/messages “Good”	User received quick-reply clicked on good, take action action accordingly
			⟸ ⟸	Await 1s Ok, i'm transferring you to a human" transfer Await 20s “Transfer failed, please try again later” close	Response	Transfer the user, and notify the user about it. Schedule a message in case the transfer fail. The message is not going to be sent if the transfer is successful
03:43	“Ok, i'm transferring you to a human”		⟹		POST /conversations/:conversationId/messages “Ok, i'm transferring you to a human"	Do not reply to your own message
			⟸	(empty replies)	Response

Provide iAdvize with your first messages as an introduction

This endpoint allows you to send iAdvize the messages displayed when the chatbox is opened and before the visitor initiates the conversation.

Please note that your bot must return a response in less than 2 seconds. Otherwise, you'll receive a timeout and the bot messages will not be displayed to the user.

GET /bots/:operatorId/conversation-first-messages

Parameters	In	Description	Type	Example
idConnectorVersion	Query	Connector version identifier	UUID	c008849d-7cb1-40ca-9503-d6df2c5cddd8
idOperator	Path	iAdvize bot operator identifier that we associate to your bot scenario	String	ha-123

Expected response from your API

Field	In	Description	Type	Required	Example
replies	Body	Array of replies	Array or Reply	✓
reply.type	Body	Reply/action type	message (other types will be ignored)	✓
reply.payload	Body	Typed payload of the message	MessagePayload
reply.quickReplies	Body	Quick replies proposed to the visitor	QuickReply[]

Example

{
   "replies":[
      {
         "type":"message",
         "payload":{
            "contentType":"text",
            "value":"Hi, my name is robot and I'm here to help"
         },
         "quickReplies":[]
      },
      {
         "type":"message",
         "payload":{
            "contentType":"text",
            "value":"How can I help you ?"
         },
         "quickReplies":[
            {
               "contentType":"text/quick-reply",
               "value":"I didn't receive my order"
            },
            {
               "contentType":"text/quick-reply",
               "value":"Payment problem"
            }
         ]
      }
   ]
}

You can validate your response data format with the associated json schema

Handling conversation creation

Everytime a conversation starts in iAdvize, this endpoint is called. It allows iAdvize to notify your external bot a conversation starts.

In most cases, leave the replies array empty as another call to POST /conversations/:conversationId/messages is triggered right after the POST /conversationscall. It will be the right time to answer the visitor.

But when a first chatbot handled the conversation and transferred it to your chatbot, the history field will contain an operator message "TRANSFERRED". If so, you must fill the "replies" tab in your response.

POST /conversations

Parameters	In	Description	Type	Example
idConnectorVersion	Query	Connector version identifier	UUID	c008849d-7cb1-40ca-9503-d6df2c5cddd8
idWebsite	Query	Unique identifier of the website on which your connector is installed	String	ha-123

Field	In	Description	Type	Example
idOperator	Body	iAdvize bot operator identifier that we associate to your bot scenario	String	ha-456678
idConversation	Body	iAdvize conversation ID	UUID	ce41ba2c-c25a-4351-b946-09527d8b940b
history	Body	First messages of the conversations	Array of History
history.idMessage	Body	Unique identifier of this message	UUID	ba4e1f71-7012-4b1a-86c3-d2fce8883dc7
history.author.role	Body	author of the message	One of: operator or visitor	operator
history.payload	Body	Typed payload of the message	One of Payload object see Payload objects for more details
history.createdAt	Body	Date the message was sent	String - ISO 8601	2018-07-16T13:53:57.961Z

Expected response from your API

Field	In	Description	Type	Required	Example
idConversation	Body	Your internal conversation ID or you can also use the iAdvize one, we will make the join for you	String	✓	ce41ba2c-c25a-4351-b946-09527d8b940b
idOperator	Body	iAdvize bot operator identifier that we associate to your bot scenario	String	✓	ha-456678
replies	Body	Array of replies	Array of Reply	✓	[]
createdAt	Body	Creation date of the conversation	String - ISO 8601	✓
updatedAt	Body	Date of the last message received	String - ISO 8601	✓

Example 1: common scenario

{
    "idConversation": "ce41ba2c-c25a-4351-b946-09527d8b940b",
    "idOperator": "ha-456678",
    "replies": [],
    "createdAt": "2017-11-22T12:04:00Z",
    "updatedAt": "2017-11-22T12:23:00Z"
}

Example 2: when a conversation is transferred to your bot

You will received the following payload from iAdvize:

{
  "idConversation": "ce41ba2c-c25a-4351-b946-09527d8b940b",
  "idOperator": "ha-456678",
  "history": [
    {
      "idMessage": "f2c214e7-9627-4821-93f1-85f7492968a8",
      "author": {
        "role": "operator"
      },
      "payload": {
        "value": "TRANSFERRED",
        "contentType": "text"
      },
      "createdAt": "2017-11-22T12:04:00Z"
    }
  ]
}

You'll have to return the following payload:

{
    "idConversation": "ce41ba2c-c25a-4351-b946-09527d8b940b",
    "idOperator": "ha-456678",
    "replies": [
      {
        "type": "message",
        "payload": {
          "contentType": "text",
          "value": "Hi ! How can I help you ?"
        },
        "quickReplies": []
      }
    ],
    "createdAt": "2017-11-22T12:04:00Z",
    "updatedAt": "2017-11-22T12:23:00Z"
}

Receive and reply to messages

This endpoint is called when a new message is received in the iAdvize conversation, whether the bot or the user sent it.

POST /conversations/:conversationId/messages

Parameters	In	Description	Type	Example
idConnectorVersion	Query	Connector version identifier	UUID	c008849d-7cb1-40ca-9503-d6df2c5cddd8
idWebsite	Query	Unique identifier of the website on which your connector is installed	String	ha-123
idConversation	Path	Conversation unique identifier	UUID	a0c65ae0-4e04-4909-a5cc-80dd0f05de96

Field	In	Description	Type	Example
idOperator	Body	iAdvize bot operator identifier that we associate to your bot scenario	String	ha-456678
message	Body	Message
message.idMessage	Body	Unique identifier of this message	String	ba4e1f71-7012-4b1a-86c3-d2fce8883dc7
message.author.role	Body	author of the message	One of: operator or visitor	operator
message.payload	Body	Typed payload of the message	One of Payload object see Payload objects for more details
message.createdAt	Body	Date the message was sent	String	2017-11-22T12:04:00.762Z

Expected response from your API

Field	In	Description	Type	Required	Example
idConversation	Body	Conversation unique identifier	UUID	✓	a0c65ae0-4e04-4909-a5cc-80dd0f05de96
idOperator	Body	iAdvize bot operator identifier that we associate to your bot scenario	String	✓	ha-456678
replies	Body	Array of replies	Array or Reply	✓
reply.type	Body	Reply/action type	One of: await or message or transfer or close	✓
reply.duration.unit	Body	Awaiting unit of time	One of: millis or seconds or minutes	Required if replies.type is equal to await
reply.duration.value	Body	Awaiting value of time	Long	Required if replies.type is equal to await
reply.payload	Body	Typed payload of the message	MessagePayload	Only available and required if reply.type is equal to message
reply.quickReplies	Body	Quick replies proposed to the visitor	QuickReply[]
reply.distributionRule	Body	Distribution rules to transfer to	UUID	Required if reply.type is equal to transfer
reply.transferOptions	Body	Transfer options	Object
reply.transferOptions.timeout	Body	Configure how long must we wait until transfer cancel	Object	✓
reply.transferOptions.timeout.value	Body	Transfer timeout value (must be between 5 and 60 seconds)	Long	✓
reply.transferOptions.timeout.unit	Body	Transfer timeout unit	One of: millis or seconds or minutes	✓
createdAt	Body	Creation date of the conversation	String - ISO 8601	✓
updateAt	Body	Date of the last message received	String - ISO 8601	✓

Example

{
    "idConversation": "ce41ba2c-c25a-4351-b946-09527d8b940b",
    "idOperator": "ha-456678",
    "replies": [
        {
            "type": "await",
            "duration": {
                "unit": "millis",
                "value": 10
            }
        },
        {
            "type": "message",
            "payload": {
                "contentType": "text",
                "value": "All Right, my job is done here."
             },
            "quickReplies": []
        },
        {
            "type": "transfer",
            "distributionRule": "ef4670c3-d715-4a21-8226-ed17f354fc44",
            "transferOptions": {
              "timeout": {
                "value": 20,
                "unit": "seconds"
              }
            }
        },
        {
            "type": "close"
        }
    ],
    "createdAt": "2017-11-22T12:04:00Z",
    "updatedAt": "2017-11-22T12:23:00Z"
}

Proactively send messages to the visitor

🎉 Through our GraphQL API you can now proactively send messages to the visitor after the conversation has started. You no longer need to wait for the visitor to systematically send you a message to get a chance to respond.

So, if you think your response to the POST /conversations/:conversationId/messages might take some time (if you call an external APIs for example), you can send it asynchronously with this new endpoint.

Note 1: this option does not exempt you from implementing the previous endpoint POST /conversations/:idConversation/messages (however, you can just reply an empty response list and only use this new way to answer the visitor).

Note 2: with this solution you can only send one "message" (or action) at a time and only after the conversation has started (= after the visitor has sent a first message).

Note 3: iAdvize will close the conversation automatically if there are no new messages for more than 5 minutes. So if you have performed a task that can potentially take more than 5 minutes, you can send a message at regular intervals to inform the visitor.

The chatbotMessageSend GraphQL mutation

Here is an example of a query that will send the message "Hello world!" in the conversation 34562f45-187c-4290-976e-1b992b7b9799 via your iAdvize chatbot id (external bot id) 123456.

mutation SendProactiveMessage {
  chatbotMessageSend(
    input: {
      conversationId: "34562f45-187c-4290-976e-1b992b7b9799",
      chatbotId: 123456,
      actionOrMessage: {
        chatbotMessage: {
          chatbotSimpleTextMessage: "Hello world!"
        }
      }
    }
  ) {
    userErrors {
      __typename
    }
  }
}

conversationId

This is the id of the iAdvize conversation you receive on the POST /conversation route in the body (idConversation).

If you return your own conversation id in the body of the call to POST /conversations, be careful not to use the conversation id passed by iAdvize in the call to POST /conversations/:conversationId/messages (because it will be your own conversation id and not the one from iAdvize).

chatbotId

This is the id of your external bot (=chatbotId) at iAdvize in integer format

The format of the operator id you receive in the REST endpoints you have implemented is slightly different: it is a string containing the operator id (=chatbotId) prefixed with the iAdvize environment sd- or ha-.

One possibility is to split the hyphen (-) and get the platform on one hand and the operator id (=chatbotId) on the other hand.

Using our integration with Apollo, you can learn more about the different options you have to interact with the visitor.