Event Webhooks
Event Webhooks give you visibility into every turn of your bot’s conversation in real-time via HTTP Callbacks. When you create a Webhook you specify the events you want to receive and these are fired as they occur.
All Autopilot REST API resources use the following base URL.
https://autopilot.twilio.com/v1/
Managing Event Webhooks from the Twilio Console
You can manage the Autopilot Event Webhooks from the Twilio Console going to your Assistant and clicking Webhooks in the menu. This will take you to the configuration screen where you can add and delete Event Webhooks.
Twilio can send your web application an HTTP request when certain events happen, such as an incoming text message to one of your Twilio phone numbers. These requests are called webhooks, or status callbacks. For more, check out our guide to Getting Started with Twilio Webhooks. Find other webhook pages, such as a security guide and an FAQ in the Webhooks section of the docs.
Webhook Properties
| Resource Properties in REST API format | |
|---|---|
url
|
The absolute URL of the Webhook resource. |
account_sid
|
The SID of the Account that created the Webhook resource. |
date_created
|
The date and time in GMT when the resource was created specified in RFC 2822 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in RFC 2822 format. |
assistant_sid
|
The SID of the Assistant that is the parent of the resource. |
sid
|
The unique string that we created to identify the Webhook resource. |
unique_name
|
An application-defined string that uniquely identifies the resource. It can be used in place of the resource's |
events
|
The list of space-separated events that this Webhook is subscribed to. |
webhook_url
|
The URL associated with this Webhook. |
webhook_method
|
The method used when calling the webhook's URL. |
Create a Webhook resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Webhooks
Creates a new Event Webhook.
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the new resource. |
unique_name
Required
|
An application-defined string that uniquely identifies the new resource. It can be used as an alternative to the |
events
Required
|
The list of space-separated events that this Webhook will subscribe to. |
webhook_url
Required
|
The URL associated with this Webhook. |
webhook_method
Optional
|
The method to be used when calling the webhook's URL. |
Example 1
Events
The events paramater can contain one or all of the following values (space separtated).
|
Event |
Description |
|
onDialogueStart |
A user starts a dialogue with the bot. |
|
onDialogueTurn |
The bot responds to the user's query. |
|
onDialogueEnd |
A user ends the dialogue. |
|
onDialogueTaskStart |
Fired when a Task is first invoked. |
|
onDialogueTaskEnd |
Fired when a Task is concluded |
|
onActionsFetch |
Fired each time Autopilot requests the Actions JSON. |
|
onCollectAttempt |
Fired each time a Collect question is answered. |
Fetch a Webhook resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Webhooks/{Sid}
Returns the Webhook instance identified by {WebhookSid}
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the resource to fetch. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Webhook resource to fetch. |
Example 1
Read multiple Webhook resources
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Webhooks
Returns a list of Webhooks for a given Assistant specified by{AssistantSid}. The list includes paging information.
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the resources to read. |
Example 1
Update a Webhook resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Webhooks/{Sid}
Updates the specific Webhook.
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the resource to update. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Webhook resource to update. |
unique_name
Optional
|
An application-defined string that uniquely identifies the new resource. It can be used as an alternative to the |
events
Optional
|
The list of space-separated events that this Webhook will subscribe to. |
webhook_url
Optional
|
The URL associated with this Webhook. |
webhook_method
Optional
|
The method to be used when calling the webhook's URL. |
Example 1
Delete a Webhook resource
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Webhooks/{Sid}
Parameters
| Parameters in REST API format | |
|---|---|
assistant_sid
Path
|
The SID of the Assistant that is the parent of the resources to delete. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Webhook resource to delete. |
Example 1
Webhook Event Parameters
Every event should include the following parameters
|
Parameter |
Description |
Example |
|
Sid |
A unique Identifier for the Event |
f60e7708db371f4005c432c1f038a6fc |
|
EventDate |
The date and time in GMT when the event was fired specified in RFC 2822 format. |
2019-09-09 13:45:00 |
|
WebhookSid |
The unique identifier of the webhook configuration |
UMf60e7708db371f4005c432c1f038a6fc |
|
Event |
The name of the event being fired |
onDialogueStart |
|
AccountSid |
Your Twilio account ID. It is 34 characters long, and always starts with the letters AC. |
ACf60e7708db371f4005c432c1f038a6fc |
|
AssistantSid |
The Autopilot assistant ID. It is 34 characters long, and always starts with UA. |
UAf60e7708db371f4005c432c1f038a6fc |
|
DialogueSid |
The session identifier. It is 34 characters long, and always starts with the letters UK. |
UKf60e7708db371f4005c432c1f038a6fc |
|
UserIdentifier |
The unique user identifier coming from the channel. For Voice and SMS it will be the user's phone number. |
+17736774656 |
|
CurrentTask |
The user's current task. |
make-reservation |
|
Language |
The language this dialogue is taking place. |
en-US |
|
DialoguePayloadUrl |
A URL to the Dialogue JSON payload that contains the context and data collected during the Autopilot session. |
https://autopilot.twilio.com/../UKf60e7708db371f4005c432c1f038a6fc |
|
Memory |
A JSON Payload that contains all the Autopilot memory values. NOTE: Memory is only sent in POST requests to prevent query params from getting truncated. |
{ "name":"Johanna" } |
|
Channel |
The channel the interaction is taking place. |
voice |
Below are the specific parameters that should be included for each event:
onDialogueStart
|
Parameter |
Description |
Example |
|
DialogueEntryPoint |
The first task of the Dialogue |
welcome-greeting |
onDialogueTurn
|
Parameter |
Description |
Example |
|
CurrentInput |
The last thing the user said |
I'm hungry |
| Fields |
A json array with the fields recognized. The array is empty if no fields were recognized. |
{ "fields":[{ "name":"reservation_date", "type":"Twilio.DATE", "value":"2019-04-16" },{ "name":"reservation_time", "type":"reservation_time", "value":"14:00" }] } |
| AssistantResponse |
The Assistants response for this task |
|
onDialogueEnd
|
Parameter |
Description |
Example |
|
DialogueEndReason |
The reason why the dialogue ended. It can be one of:
Please note that the onDialogueEnd event will not fire if the dialogue times out. |
handoff |
onDialogueTaskStart
|
Parameter |
Description |
Example |
|
InvocationMethod |
The method how this task was invoked. It can be one of:
|
listen |
onDialogueTaskEnd
|
Parameter |
Description |
Example |
|
TaskEndReason |
The method how this task ended. It can be one of:
|
handoff |
onCollectAttempt
|
Parameter |
Description |
Example |
|
CollectName |
The name of the collect where the attempt was performed |
ask_reservation_details |
|
CollectSid |
The Collect Attempt ID. It is 34 characters long, and always starts with CT. |
ULf60e7708db371f4005c432c1f038a6fc |
|
CollectFieldType |
The field type of the expected answer |
Twilio.DATE |
|
CollectAttempt |
The attempt number. It represents the number of tries attempting to answer the question. |
1 |
|
CollectFieldFilled |
true if the field is filled, false otherwise |
true |
|
CollectFieldName |
The field name of the question being asked |
reservation_date |
|
CollectSuccess |
Whether the collect was successful or not. If there was data type validation issues the collect would not be successful. If there are any allowed values or webhook validation failures the collect would still be considered successful |
true |
|
CollectErrorMessage |
The error message if one exists |
Invalid Date |
|
CollectValidation |
Whether there was validation in this question. true if there was, false otherwise. |
true |
|
CurrentInput |
What the user said |
tomorrow |
|
CollectOutput |
What the assistant understood |
2019-04-15 |
onActionsFetch
|
Parameter |
Description |
Example |
|
ActionsUrl |
The HTTP request Url used to fetch Actions |
https://www.example.com/autopilot |
|
ActionsMethod |
The HTTP request method used to fetch Actions |
POST |
|
ActionsHttpResponse |
The HTTP Response returned |
200 |
|
ActionsValidation |
The outcome of the Actions JSON schema validation. It can be valid or not-valid. |
valid |
|
ActionsError |
An error message if present |
"actions should NOT have additional properties" |
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
