conversation.step_reached

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

1000

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"
                }
            ]
        }
    }
}
AttributeTypeDescription
data.channelstringchannel used by interlocutor (facebook, intercom...)
data.inputobjectinput that triggered the execution
data.interlocutor.idstringinterlocutor's ID
data.interlocutor.location.latfloatinterlocutor's latitude
data.interlocutor.location.longfloatinterlocutor's longitude
data.interlocutor.firstNamestringinterlocutor's first name
data.interlocutor.lastNamestringinterlocutor's last name
data.interlocutor.emailstringinterlocutor's email
data.interlocutor.customAttributesobjectinterlocutor's other attributes
data.interlocutor.phoneNumberstringinterlocutor's phone number
data.session.valuesobjectinterlocutor's session's values
data.step.idstringID of step being executed
data.step.namestringname of step being executed
data.step.userDatastringcustom data set on the step with the [+] next to the "use webhook" toggle on the step form
data.step.actionsarraylist 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.

AttributeTypeRequiredDescription
actionsarray<action>list of action objects
session.valuesobjectinterlocutor's session's values
interlocutorobjectinterlocutor object
interlocutor.idstringinterlocutor's ID
interlocutor.locationobjectinterlocutor's location (can be null)
interlocutor.firstNamestringinterlocutor's first name (can be null)
interlocutor.lastNamestringinterlocutor's last name (can be null)
interlocutor.emailstringinterlocutor's email (can be null)
interlocutor.customAttributesobjectinterlocutor's other attributes
data.interlocutor.phoneNumberstringinterlocutor's phone number