conversation.step_reached

This event is triggered when you switch on the use webhook button.

When an interlocutor will reached this step while talking to your bot, a POST request will be sent to your webhook to let you decide what to do.
The bot will wait for your webhook's response in order to continue the conversation.

It allows you to override the default behavior of the step by overriding the actions that must be executed by the bot.
You can also update the session's values.

Request format

Request
{
    "topic": "conversation.step_reached",
    "botID": "507f1f77bcf86cd799439011",
    "timestamp": 1514998709,
    "type": "event",
    "data": {
        "channel": "facebook",
        "input": {
            "type": "message",
            "text:" "hello",
            "attachments": []
        },
        "interlocutor": {
            "id": "507f1f77bcf86cd799439011",
            "userID": "xxyyzz",
            "location": {
                "lat": 77.415040,
                "long": -44.052074
            },
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]",
            "customAttributes": {
                "age": "25"
            },
            "phoneNumber": null
        },
        "session": {
            "values": {
                "name": "John"
            }
        },
        "step": {
            "id": "5a8c317624acbe05b1a36feb",
            "name": "A step",
            "userData": null,
            "actions": [
                {
                    "type": "pause_bot_action"
                }
            ]
        }
    }
}

Attribute

Type

Description

data.channel

string

channel used by interlocutor (facebook, intercom...)

data.input

object

input that triggered the execution

data.interlocutor.id

string

interlocutor's ID

data.interlocutor.location.lat

float

interlocutor's latitude

data.interlocutor.location.long

float

interlocutor's longitude

data.interlocutor.firstName

string

interlocutor's first name

data.interlocutor.lastName

string

interlocutor's last name

data.interlocutor.email

string

interlocutor's email

data.interlocutor.customAttributes

object

interlocutor's other attributes

data.interlocutor.phoneNumber

string

interlocutor's phone number

data.session.values

object

interlocutor's session's values

data.step.id

string

ID of step being executed

data.step.name

string

name of step being executed

data.step.userData

string

custom data set on the step with the [+] next to the "use webhook" toggle on the step form

data.step.actions

array

list of action objects

Response format

Response
{
    "actions": [
        { 
            "type": "pause_bot_action"
        }
    ],
    "session": {
        "values": {
            "name": "John Doe"
        }
    },
    "interlocutor": {
        "id": "507f1f77bcf86cd799439011",
        "location": {
            "lat": 77.415040,
            "long": -44.052074
        },
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "customAttributes": {
            "age": "25"
        },
        "phoneNumber": null
    }
}

The response must include the list of the actions to be executed by the bot.
Optionally you can update the session's values by modifying them in the response.
If you omit the session object it will keep the session as it is, and if you set it to an empty object it will delete all the values.
Also you can update the interlocutor by providing new values for the fields you wan to update. If interlocutor is omitted in the response it won't be updated.

Attribute

Type

Required

Description

actions

array<action>

list of action objects

session.values

object

interlocutor's session's values

interlocutor

object

interlocutor object

interlocutor.id

string

interlocutor's ID

interlocutor.location

object

interlocutor's location (can be null)

interlocutor.firstName

string

interlocutor's first name (can be null)

interlocutor.lastName

string

interlocutor's last name (can be null)

interlocutor.email

string

interlocutor's email (can be null)

interlocutor.customAttributes

object

interlocutor's other attributes

data.interlocutor.phoneNumber

string

interlocutor's phone number