Skip to main content
Connecting Flex is three pieces of work: paste credentials, register the webhook on both Twilio surfaces, and add two workflow filters. Miss any one and handoff looks silently broken.
The webhook URL is scoped to a single OpenCX org and environment. Do not reuse a sandbox webhook URL against a production Twilio account — the token in the URL carries your orgId, so events will silently route to the wrong workspace. Copy the URL fresh from every environment you’re connecting.

​
Before you start

You need access to the and the parent Twilio Console to copy credentials and register webhooks.
Know the(starts with WS) you want OpenCX to join. If you have a dedicated, have its SID handy too.
You need edit access to the that routes your inbound tasks — you’ll add two filters to it before the setup is complete.

​
Save credentials in OpenCX

1

Open the Flex integration

Go to Settings → Integrations in your OpenCX dashboard and click Twilio Flex.
2

Paste credentials

Fill in the form:
OpenCX automatically provisions an in your workspace on first save — you do not create this worker yourself. Its SID is persisted inside OpenCX so your workflow filter can target it. Saving again later never creates extra workers.
3

Optional: scale the AI worker pool

Twilio caps each worker at 50 concurrent chats. If you expect more parallel conversations, use the AI Agents section in the integration settings and click Add AI Agent — each worker you add raises total capacity by 50 (2 workers = 100 concurrent chats, and so on). Every pool worker carries the same ai and support routing skills, so your workflow filter matches all of them without changes.
4

Copy the webhook URL

The Webhook URL field at the top of the modal shows the URL OpenCX will accept events on. Copy it — you’ll paste it into Twilio twice.
5

Click Test & Save

OpenCX validates the credentials against TaskRouter’s workspace API. A failure means the Account SID, Auth Token, or Workspace SID is wrong.

​
Register the webhook on TaskRouter

In the Twilio Flex Console, open TaskRouter → Workspaces → [your workspace] → Event Callbacks. Paste the OpenCX webhook URL and subscribe to the following events:
Subscribe this URL to all of these events:
  • reservation.created
  • reservation.accepted
  • reservation.timeout
  • task.created
  • workflow.target-matched
Save. TaskRouter will start delivering events immediately.

​
Register the webhook on the Conversations service

In the Twilio Console, open Conversations → Services → [your Flex Conversations service] → Webhooks. Paste the same OpenCX webhook URL and subscribe to:
Subscribe this URL to all of these filters:
  • onMessageAdded
  • onConversationAdded
  • onParticipantAdded
Save.
Both webhooks are required. Registering only the TaskRouter webhook is the single most common onboarding mistake — customer messages reach OpenCX but no task is created, because the Conversations events never arrive. Register both before moving on.

​
Add the workflow filters

Open your TaskRouter workflow and add two filters, in this order:
1

Route AI-skilled tasks to the OpenCX AI worker

If you set an AI Queue SID during credentials, filter on that queue. Otherwise, filter on the routing skills ai and support — OpenCX adds both to every AI worker it provisions, so one filter covers the whole pool. This is the filter that gets the AI a crack at the task first.
2

Route `handedOff == true` tasks to your human queue

Filter expression: handedOff == true. Target your human agent queue (support, tier 2, etc.). This is the filter OpenCX relies on after it rejects the AI reservation — without it, a handed-off task sits in limbo.

​
Verify end to end

1

Send a test message

Send a message on the channel you wired up (SMS, WhatsApp, web chat, voice call). OpenCX’s AI worker should accept the reservation and reply.
2

Check the task in Flex

Open TaskRouter → Tasks. The task should show the AI worker as the assigned worker, with conversationSid present in the task attributes.
3

Trigger a handoff

Reply with “I want to talk to a human” (or whatever handoff trigger your org uses). The task should re-route — check the attributes for handedOff: true and the reason/summary fields. Your human queue should now own the task.
If the AI never accepts, your workflow filter isn’t matching the AI worker. If the AI accepts but handoff never re-routes, the handedOff == true filter is missing. See Troubleshooting.

Handoff and task attributes

What OpenCX writes to every task on handoff.

Channels

Per-channel implementation on top of this shared setup.

Troubleshooting

Missing webhook, wrong queue, events routed to the wrong org.

Human handoff

Global handoff rules and office hours.