conversation.step

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