Skip to contentSkip to navigationSkip to topbar
On this page

Subscribe to 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

overview page anchor

The Interactions API is part of the architecture that supports Flex Conversations. Certain Interactions API operations trigger events related to an Interaction, Participant, or Channel. To get notified of events and state changes during Conversations, you can configure a webhook URL to receive Interaction events and then subscribe to selected events.

Subscribing to events lets Flex send details you need and prevents your system from receiving data you don't need. It also lets you gather information about customer interactions or trigger additional workflows in certain situations. For example, using the onParticipantLeft event, you could create a custom workflow to show a survey when a Participant leaves a Conversation.

As an administrator, you can set and manage your Interactions webhook URL and event subscriptions on the Interactions page in the Twilio Console. Developers can also register webhook URLs to receive notifications about events or specific Interactions they need to build custom workflows.


To set the webhook URL:

  1. In the Twilio Console, go to Flex > Channel management > Interactions.
  2. In Webhook URL, enter the URL where you want Flex to send Interaction event details. The URL must begin with http or https.
  3. In Webhook method, select HTTP POST or HTTP GET.

To subscribe:

  1. Under Select webhook events, select the events you want to subscribe to. See Event details for a list of events and their associated parameters.
  2. Click Save configuration.

onInteractionCreated

oninteractioncreated page anchor

Sent when an Interaction is created.

Parameter nameData typeDescription
EventTypeStringValue is always onInteractionCreated.
AccountSidSIDThe Twilio Account SID of the Interaction.
InstanceSidSIDThe Flex Instance SID of the Interaction.
InteractionSidSIDThe Interaction SID.
MediaChannelSidSIDThe Conversation SID or Conference SID that the Channel is associated with.
MediaChannelTypeStringType of Channel the Interaction occurred on. For example: sms, whatsapp, chat, or voice.

Sent when a Channel is created.

Parameter nameTypeDescription
EventTypeStringValue is always onChannelCreated.
AccountSidSIDThe Twilio Account SID of the Channel.
InstanceSidSIDThe Flex Instance SID of the Channel.
InteractionSidSIDThe Interaction SID of the Channel.
ChannelSidSIDThe SID of the Channel that was created.
MediaChannelSidSIDThe Conversation SID or Conference SID associated with the Channel.
MediaChannelTypeStringType of Channel created. For example, sms, whatsapp, web, chat, or voice.

Sent if a Channel can't be created.

Parameter nameTypeDescription
EventTypeStringValue is always onChannelCreateFailed.
AccountSidSIDThe Twilio Account SID of the Channel.
ErrorCodeIntegerThe Twilio error code for the reason that Channel creation failed.
ErrorMessageStringThe Twilio error message associated with the reason for the failure.
InteractionSidSIDThe Interaction SID of the Channel. This parameter is optional.
ChannelSidSIDThe 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.
MediaChannelSidSIDThe Conversation SID or Conference SID associated with the Channel. This parameter is optional.
MediaChannelTypeStringType 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 nameTypeDescription
EventTypeStringValue is always onChannelStatusUpdated.
AccountSidSIDThe Twilio Account SID of the Channel.
InstanceSidSIDThe Flex Instance SID of the Channel.
InteractionSidSIDThe Interaction SID that the Channel belongs to.
ChannelSidSIDThe SID of the Channel that was updated.
MediaChannelSidSIDThe Conversation SID or Conference SID associated with the Channel.
ChannelStatusSIDThe current status of the channel. Value can be active or closed.
MediaChannelTypeStringType 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 nameTypeDescription
EventTypeStringValue is always onParticipantJoined.
AccountSidSIDThe Twilio Account SID that the Participant belongs to.
InteractionSidSIDThe Interaction SID that the Participant belongs to.
ChannelSidSIDThe Channel SID of the Channel that the Participant belongs to.
ParticipantSidSIDThe SID of the Participant added to the Channel.
ParticipantTypeStringType of Participant. For example, customer or agent.
TaskSidSIDThe Task SID associated with the Channel.
MediaChannelSidSIDThe Conversation SID or Conference SID associated with the Channel.
MediaChannelTypeStringType 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 nameTypeDescription
EventTypeStringValue is always onParticipantLeft.
AccountSidSIDThe Twilio Account SID that the Participant belongs to.
InteractionSidSIDThe Interaction SID that the Participant belongs to.
ChannelSidSIDThe Channel SID of the Channel that the Participant belongs to.
ParticipantSidSIDThe SID of the Participant who left the Channel.
ParticipantTypeStringType of Participant. For example, customer or agent.
TaskSidSIDThe Task SID associated with the Channel.
MediaChannelSidSIDThe Conversation SID or Conference SID associated with the Channel.
MediaChannelTypeStringType of Channel the Participant left. For example, sms, whatsapp, web, chat, or voice.

Sent when a Participant's status is updated.

Parameter nameTypeDescription
EventTypeStringValue is always onParticipantUpdated.
AccountSidSIDThe Twilio Account SID that the Participant belongs to.
InteractionSidSIDThe Interaction SID that the Participant belongs to.
ChannelSidSIDThe Channel SID of the Channel that the Participant belongs to.
ParticipantSidSIDThe SID of the Participant whose status was updated.
ParticipantTypeStringType of Participant. For example: customer, agent.
TaskSidSIDThe Task SID associated with the Channel.
MediaChannelSidSIDThe Conversation SID or Conference SID associated with the Channel.
MediaChannelTypeStringType of Channel on which the Participant's status was updated. For example, sms, whatsapp, web, chat, or voice.