Register a webhook to receive Interactions events
Warning
Interactions API webhooks are not PCI compliant or a HIPAA Eligible Service and should not be used in Flex workflows that are subject to HIPAA or PCI.
The Interactions API is part of the architecture that supports Flex Conversations. When developing for Flex Conversations, you may need to receive Interactions events in your Flex development environment to use in building custom workflows.
To get to Interaction event notifications, use the https://flex-api.twilio.com/v1/Instances/{instanceSid}/InteractionWebhooks
API endpoint to register a webhook URL and subscribe to events you need.
There are two types of Interactions webhooks. You determine which to create by setting the Type
parameter in the API request to one of the following:
global
: Get notifications for all events you subscribe to using one webhook URL for your Flex instance. Note that you can also set a global webhook URL and subscribe to event details in the Twilio Console.interaction
: Get notifications for events you subscribe to only for a specific interaction. After registering a webhook with theType
set tointeraction
, the API response provides attid
value for that webhook. You must then provide this value as thewebhook_ttid
when you create an Interaction. This associates the webhook to the Interaction so that you get notifications when a subscribed event occurs for that Interaction.
To register a webhook URL:
- Execute the
POST /v1/Instances/{instanceSid}/InteractionWebhooks
API call, making sure that you set the request parameters according to the type of webhook you want to create. See below for example requests to create a global or an Interaction-specific webhook.
Name | Description |
---|---|
Filters | Name of the event to send to the webhook URL. See Event details for a list of events and their associated parameters. You can pass more than one instance of this parameter. |
Method | HTTP method used to send the event. |
Type | Type of webhook. Possible values:
global . |
WebhookUrl | Webhook URL to send the event details. |
FriendlyName | A name for the webhook that's easy to recognize and understand. |
Note: If you register a global webhook URL for all events and an Interaction-specific webhook URL, when an event you've subscribed to occurs for an Interaction you've subscribed to, Flex sends a notification to both URLs.
The following are examples of the POST /v1/Instances/{instanceSid}/InteractionWebhooks
API call configured by type
.
1curl -X POST https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks \\2--data-urlencode "WebhookEvents=onChannelUpdated" \\3--data-urlencode "WebhookEvents=onChannelCreateFailed" \\4--data-urlencode "WebhookMethod=POST" \\5--data-urlencode "Type=global" \\6--data-urlencode "WebhookUrl=https://company.com/action" \\7-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
1{2"ttid": "flex_interactionwebhook_XXXXXXXXXXXXXXXXXXX" "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "instance_sid": "GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",3"webhook_url": "https://company.com/filtering-and-permissions",4"webhook_events": [ "onChannelUpdated", "onChannelCreateFailed"],5"webhook_method": "POST", "type": "global",6"url": "https://flex-api.twilio.com/v1/Interactions/Webhooks)/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks/flex_interactionwebhook_xxxx"7}
Calling the following API creates an Interaction-specific webhook to receive notifications for subscribed WebhookEvents
at the specified WebhookUrl
.
This API returns a ttid
value that you must pass in the Interactions API webhook_ttid
parameter when you create the Interaction you want to associate with the webhook.
You must call both this API and the Interactions API for an Interaction-specific webhook to work correctly. After sending this request, you won't receive event notifications until you call the Interactions API to create an interaction and include the ttid
value returned by this request. To see an example request that creates an Interaction associated with a webhook, go to the Interactions resource.
1curl -X POST https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks2--data-urlencode "WebhookEvents=onChannelUpdated"3--data-urlencode "WebhookEvents=onChannelCreateFailed"4--data-urlencode "WebhookMethod=POST"5--data-urlencode "Type=interaction"6--data-urlencode 'FriendlyName=Friendly Name of webhook'7--data-urlencode "WebhookUrl=https://company.com/action"8-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
1{2"ttid": "flex_interactionwebhook_XXXXXXXXXXXXXXXXXXX",3"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",4"instance_sid": "GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",5"webhook_url": "https://company.com/filtering-and-permissions",6"webhook_events": [ "onChannelUpdated", "onChannelCreateFailed" ],7"webhook_method": "POST",8"friendly_name": "Friendly Name of webhook",9"type": "interaction",10"url": "https://flex-api.twilio.com/v1/Interactions/Webhooks"11}
Sent when an Interaction is created.
Parameter name | Data type | Description |
---|---|---|
EventType | String | Value is always onInteractionCreated . |
AccountSid | SID | The Twilio Account SID of the Interaction. |
InstanceSid | SID | The Flex Instance SID of the Interaction. |
InteractionSid | SID | The Interaction SID. |
MediaChannelSid | SID | The Conversation SID or Conference SID that the Channel is associated with. |
MediaChannelType | String | Type of Channel the Interaction occurred on. For example: sms , whatsapp , chat , or voice . |
Sent when a Channel is created.
Parameter name | Type | Description |
---|---|---|
EventType | String | Value is always onChannelCreated . |
AccountSid | SID | The Twilio Account SID of the Channel. |
InstanceSid | SID | The Flex Instance SID of the Channel. |
InteractionSid | SID | The Interaction SID of the Channel. |
ChannelSid | SID | The SID of the Channel that was created. |
MediaChannelSid | SID | The Conversation SID or Conference SID associated with the Channel. |
MediaChannelType | String | Type of Channel created. For example, sms , whatsapp , web , chat , or voice . |
Sent if a Channel can't be created.
Parameter name | Type | Description |
---|---|---|
EventType | String | Value is always onChannelCreateFailed . |
AccountSid | SID | The Twilio Account SID of the Channel. |
ErrorCode | Integer | The Twilio error code for the reason that Channel creation failed. |
ErrorMessage | String | The Twilio error message associated with the reason for the failure. |
InteractionSid | SID | The Interaction SID of the Channel. This parameter is optional. |
ChannelSid | SID | The SID of the Channel created. This parameter is optional. Note In some cases, a ChannelSid is created even though the Channel itself isn't created successfully. For example, this can happen if Channel creation fails because of a failure with a downstream resource. |
MediaChannelSid | SID | The Conversation SID or Conference SID associated with the Channel. This parameter is optional. |
MediaChannelType | String | Type of Channel that couldn't be created. For example, sms , whatsapp , chat , or voice . |
Sent when the Channel status is updated. The status can be active
or closed
.
Parameter name | Type | Description |
---|---|---|
EventType | String | Value is always onChannelStatusUpdated . |
AccountSid | SID | The Twilio Account SID of the Channel. |
InstanceSid | SID | The Flex Instance SID of the Channel. |
InteractionSid | SID | The Interaction SID that the Channel belongs to. |
ChannelSid | SID | The SID of the Channel that was updated. |
MediaChannelSid | SID | The Conversation SID or Conference SID associated with the Channel. |
ChannelStatus | SID | The current status of the channel. Value can be active or closed . |
MediaChannelType | String | Type of Channel updated. For example, sms , whatsapp , web , chat , or voice . |
Sent when a Participant is added to the Channel. Occurs when:
- The Participant accepts a reservation.
- The Participant is added using the Add Participant API.
Parameter name | Type | Description |
---|---|---|
EventType | String | Value is always onParticipantJoined . |
AccountSid | SID | The Twilio Account SID that the Participant belongs to. |
InteractionSid | SID | The Interaction SID that the Participant belongs to. |
ChannelSid | SID | The Channel SID of the Channel that the Participant belongs to. |
ParticipantSid | SID | The SID of the Participant added to the Channel. |
ParticipantType | String | Type of Participant. For example, customer or agent. |
TaskSid | SID | The Task SID associated with the Channel. |
MediaChannelSid | SID | The Conversation SID or Conference SID associated with the Channel. |
MediaChannelType | String | Type of Channel the Participant joined. For example, sms , whatsapp , web , chat , or voice . |
Sent when a Participant leaves the Channel. Occurs when the Participant leaves the Channel.
Parameter name | Type | Description |
---|---|---|
EventType | String | Value is always onParticipantLeft . |
AccountSid | SID | The Twilio Account SID that the Participant belongs to. |
InteractionSid | SID | The Interaction SID that the Participant belongs to. |
ChannelSid | SID | The Channel SID of the Channel that the Participant belongs to. |
ParticipantSid | SID | The SID of the Participant who left the Channel. |
ParticipantType | String | Type of Participant. For example, customer or agent. |
TaskSid | SID | The Task SID associated with the Channel. |
MediaChannelSid | SID | The Conversation SID or Conference SID associated with the Channel. |
MediaChannelType | String | Type of Channel the Participant left. For example, sms , whatsapp , web , chat , or voice . |
Sent when a Participant's status is updated.
Parameter name | Type | Description |
---|---|---|
EventType | String | Value is always onParticipantUpdated . |
AccountSid | SID | The Twilio Account SID that the Participant belongs to. |
InteractionSid | SID | The Interaction SID that the Participant belongs to. |
ChannelSid | SID | The Channel SID of the Channel that the Participant belongs to. |
ParticipantSid | SID | The SID of the Participant whose status was updated. |
ParticipantType | String | Type of Participant. For example: customer, agent. |
TaskSid | SID | The Task SID associated with the Channel. |
MediaChannelSid | SID | The Conversation SID or Conference SID associated with the Channel. |
MediaChannelType | String | Type of Channel on which the Participant's status was updated. For example, sms , whatsapp , web , chat , or voice . |
The GET /v1/Instances/{instanceSid}/InteractionWebhooks
API call lets you get a list of all your registered webhooks.
Query parameter: type
1curl -X GET https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks{ttid} \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
1{2"meta": {3"page": 0,4"page_size": 50,5"first_page_url": "https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks?PageSize=50\&Page=0",6"previous_page_url": null,7"url": "https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks?PageSize=50&Page=0",8"next_page_url": null,9"key": "data"10},11"data": [12{13"ttid": "flex_interactionwebhook_XXXXXXXXXXXXXXXXXXX",14"instance_sid": "GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",15"url": "https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks/flex_interactionwebhook_XXXXXXXXXXXXXXXXXXX",16"webhook_events": ["onInteractionCreated","onChannelCreated"],17"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",18"webhook_method": "POST",19"webhook_url": "https://interaction-webbhook-6314.twil.io/interaction",20"type": "global"21},22{23"ttid": "flex_interactionwebhook_XXXXXXXXXXXXXXXXXXX",24"instance_sid": "GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",25"url": "https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks/flex_interactionwebhook_XXXXXXXXXXXXXXXXXXX",26"webhook_events": ["onInteractionCreated","onChannelCreated"],27"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",28"webhook_method": "POST",29"webhook_url": "https://interaction-webbhook-6314.twil.io/interaction",30"type": "interaction"31}32]33}
The GET /v1/Instances/{instanceSid}/InteractionWebhooks/{ttid}
API call lets you get the details for a webhook.
1curl -X GET https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks/flex_interactionwebhook_xxxx2\-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
1{2"ttid": "flex_interactionwebhook_XXXXXXXXXXXXXXXXXXX"3"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",4"instance_sid": "GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",5"webhook_url": "https://company.com/filtering-and-permissions",6"webhook_eventsfilters": [ "onChannelUpdated", "onChannelCreateFailed" ],7"webhook_method": "POST",8"type": "global",9"url": "https://flex-api.twilio.com/Interactions/Webhooks)/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks/flex_interactionwebhook_xxxx"10}
POST /v1/Instances/{instanceSid}/InteractionWebhooks/{ttid}
1curl -X POST https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks/**flex_interactionwebhook_XXXXXXXXXXXXXXXXXXX**2--data-urlencode "WebhookEvents=onChannelUpdated"3--data-urlencode "WebhookEvents=onInteractionCreated"4--data-urlencode "WebhookMethod=POST"5--data-urlencode "WebhookUrl=https://company.com/action"6--data-urlencode "FriendlyName=Friendly Name of webhook"7-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
1{2"ttid": "flex_interactionwebhook_XXXXXXXXXXXXXXXXXXX"3"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",4"instance_sid": "GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",5"webhook_url": "https://company.com/action",6"webhook_events": [ "onChannelUpdated", "onInteractionCreated" ],7"webhook_method": "POST",8"type": "global",9"friendly_name": "Friendly Name of webhook",10"url": "https://flex-api.twilio.com/v1/Interactions/Webhooks)/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks/flex_interactionwebhook_xxxx"11}
The DELETE /v1/Instances/{instanceSid}/InteractionWebhooks/{ttid}
API call lets you delete a webhook.
1curl -X DELETE https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks/flex_interactionwebhook_xxxx2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN