Register a webhook to receive Interactions events

(warning)

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.

Overview

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.

Register an Interaction webhook URL

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 the Type set to interaction, the API response provides a ttid value for that webhook. You must then provide this value as the webhook_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.

Request parameters

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`: Send a notification every time the subscribed events occur. `interaction`: Send a notification for the subscribed events when they occur for a specific interaction. If you don’t send a value in the request, it defaults to `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.

Register a global Interaction webhook

POST API request

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

POST API response

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}

Register an Interaction webhook for a specific Interaction

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.

POST API request

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=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

POST API response

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}

Event details

onInteractionCreated

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`.

onChannelCreated

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`.

onChannelCreateFailed

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`.

onChannelStatusUpdated

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`.

onParticipantJoined

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`.

onParticipantLeft

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`.

onParticipantUpdated

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`.

Get a list of all Interaction webhooks registered for your Flex instance

The GET /v1/Instances/{instanceSid}/InteractionWebhooks API call lets you get a list of all your registered webhooks.

Query parameter: type

GET API request

1curl -X GET https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks{ttid} \
2  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

GET API response

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}

Get details for an Interaction webhook

The GET /v1/Instances/{instanceSid}/InteractionWebhooks/{ttid} API call lets you get the details for a webhook.

GET API request

1curl -X GET https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks/flex_interactionwebhook_xxxx
2\-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

GET API response

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}

Update an Interaction webhook

POST /v1/Instances/{instanceSid}/InteractionWebhooks/{ttid}

POST API request

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

POST API response

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}

Delete an Interaction webhook

The DELETE /v1/Instances/{instanceSid}/InteractionWebhooks/{ttid} API call lets you delete a webhook.

DELETE API request

1curl -X DELETE https://flex-api.twilio.com/v1/Instances/GOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/InteractionWebhooks/flex_interactionwebhook_xxxx
2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN