Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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/

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

Names in PHP format
url
url Not PII

The absolute URL of the Webhook resource.

accountSid
sid<AC> Not PII

The SID of the Account that created the Webhook resource.

dateCreated
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in RFC 2822 format.

dateUpdated
date_time<iso8601> Not PII

The date and time in GMT when the resource was last updated specified in RFC 2822 format.

assistantSid
sid<UA> Not PII

The SID of the Assistant that is the parent of the resource.

sid
sid<UM> Not PII

The unique string that we created to identify the Webhook resource.

uniqueName
string Not PII

An application-defined string that uniquely identifies the resource. It can be used in place of the resource's sid in the URL to address the resource.

events
string Not PII

The list of space-separated events that this Webhook is subscribed to.

webhookUrl
url Not PII

The URL associated with this Webhook.

webhookMethod
string Not PII

The method used when calling the webhook's URL.

Create a Webhook resource

post
https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Webhooks

Creates a new Event Webhook.

Parameters
Names in None format
assistant_sid
Required
post sid_like<UA> Not PII

The SID of the Assistant that is the parent of the new resource.

unique_name
Required
post string Not PII

An application-defined string that uniquely identifies the new resource. It can be used as an alternative to the sid in the URL path to address the resource. This value must be unique and 64 characters or less in length.

events
Required
post string Not PII

The list of space-separated events that this Webhook will subscribe to.

webhook_url
Required
post url Not PII

The URL associated with this Webhook.

webhook_method
Optional
post string Not PII

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.

        onDialogueEnd

        A user ends the dialogue.

        onDialogueTaskStart

        Fired when a Task is first invoked.

        onActionsFetch

        Fired each time Autopilot requests the Actions JSON.


        onCollectAttempt

        Fired each time a Collect question is answered.

        Fetch a Webhook resource

        get
        https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Webhooks/{Sid}

        Returns the Webhook instance identified by {WebhookSid}

        Parameters
        Names in None format
        assistant_sid
        Required
        get sid_like<UA> Not PII

        The SID of the Assistant that is the parent of the resource to fetch.

        sid
        Required
        get sid_like<UM> Not PII

        The Twilio-provided string that uniquely identifies the Webhook resource to fetch.

        Example 1
              
              
              
              

              Read multiple Webhook resources

              get
              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
              Names in None format
              assistant_sid
              Required
              get sid_like<UA> Not PII

              The SID of the Assistant that is the parent of the resources to read.

              Example 1
                    
                    
                    
                    

                    Update a Webhook resource

                    post
                    https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Webhooks/{Sid}

                    Updates the specific Webhook.

                    Parameters
                    Names in None format
                    assistant_sid
                    Required
                    post sid_like<UA> Not PII

                    The SID of the Assistant that is the parent of the resource to update.

                    sid
                    Required
                    post sid_like<UM> Not PII

                    The Twilio-provided string that uniquely identifies the Webhook resource to update.

                    unique_name
                    Optional
                    post string Not PII

                    An application-defined string that uniquely identifies the new resource. It can be used as an alternative to the sid in the URL path to address the resource. This value must be unique and 64 characters or less in length.

                    events
                    Optional
                    post string Not PII

                    The list of space-separated events that this Webhook will subscribe to.

                    webhook_url
                    Optional
                    post url Not PII

                    The URL associated with this Webhook.

                    webhook_method
                    Optional
                    post string Not PII

                    The method to be used when calling the webhook's URL.

                    Example 1
                          
                          
                          
                          

                          Delete a Webhook resource

                          delete
                          https://autopilot.twilio.com/v1/Assistants/{AssistantSid}/Webhooks/{Sid}
                          Parameters
                          Names in None format
                          assistant_sid
                          Required
                          delete sid_like<UA> Not PII

                          The SID of the Assistant that is the parent of the resources to delete.

                          sid
                          Required
                          delete sid_like<UM> Not PII

                          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

                                onDialogueEnd

                                Parameter

                                Description

                                Example

                                DialogueEndReason

                                The reason why the dialogue ended. It can be one of:

                                • timeout
                                • handoff
                                • end_of_actions
                                • error

                                handoff

                                onDialogueTaskStart

                                Parameter

                                Description

                                Example

                                InvocationMethod

                                The method how this task was invoked. It can be one of:

                                • initiation
                                • fallback
                                • collect_on_failure
                                • listen
                                • redirect

                                listen

                                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"

                                Rate this page:

                                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 browsing the Twilio tag on Stack Overflow.