Skip to main content
Before debugging, have this ready:
  • Your Twilio and the Flex .
  • A specific OpenCX session ID (from Inbox) or the Flex task SID where the problem shows.
  • The webhook URL shown in Settings → Integrations → Twilio Flex.
Re-run Test & Save in Settings → Integrations → Twilio Flex as your first step. Most issues are credential or webhook related.
Fastest path to root cause: search the Inbox by the flex_task_sid, flex_conversation_sid, or flex_reservation_sid stored on the OpenCX session. That opens the full AI reasoning and handoff event — far faster than trawling Twilio’s event log.

​
Common scenarios

Jump to the symptom that matches what you’re seeing.

​
”Failed to verify credentials” on save

: wrong Workspace SID, or account-level Auth Token mismatch. Fix: re-copy the Account SID and Auth Token from the Twilio Console dashboard. Re-copy the Workspace SID from Flex Console → Configuration → Workspace. Confirm they belong to the same Twilio account.

​
Handoff runs but the task stays in the AI queue

: missing handedOff == true workflow filter. Fix: open your TaskRouter workflow and add a filter with expression handedOff == true targeting your human queue. Place it before the AI filter so a handed-off task matches humans first. Re-run a test handoff.

​
Customer messages reach OpenCX but no Flex task is created

: only the TaskRouter webhook is registered; the Conversations service webhook is missing. Fix: in the Twilio Console, open Conversations → Services → [your Flex Conversations service] → Webhooks. Paste the same OpenCX webhook URL and subscribe to onMessageAdded, onConversationAdded, and onParticipantAdded. Both webhooks must be registered.

​
Events routed to the wrong org

: a sandbox webhook URL was pasted into a production Twilio account. Fix: copy the webhook URL freshly from each environment’s Settings → Integrations → Twilio Flex page. Never copy one environment’s URL into another. Update the URL on both TaskRouter and the Conversations service.

​
None of the above

Open a support request with the Flex task SID, the OpenCX session ID (if any), and a timestamp.

​
Limits and best-effort behavior

Value
Duplicate message dedup window1 hour (hash of conversation SID + body + send timestamp)
Outbound sendBest-effort — retries on transient Twilio failures; does not block handoff on send failure
Flex task closureCustomer-side — OpenCX never calls task.complete()
AI worker provisioningAutomatic on first settings save; persists until you delete it in Flex
OpenCX retries on transient Twilio failures but does not indefinitely retry past rate limits. If your Twilio account hits its per-minute cap, expect intermittent late deliveries until the window resets.

Connect Twilio Flex

Re-verify credentials, webhooks, and workflow filters.

Handoff and task attributes

Re-verify the task-attribute contract.

Twilio Flex overview

What Flex lights up across every channel.

Human handoff

Global handoff rules and office hours.