> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Twilio Flex troubleshooting

> Debug Flex credential errors, missing webhooks, tasks landing in the wrong queue, and duplicate messaging.

Before debugging, have this ready:

* Your Twilio <Tooltip tip="The Twilio Account SID and Auth Token you pasted into OpenCX. Starts with AC for the Account SID.">Account SID</Tooltip> and the Flex <Tooltip tip="The TaskRouter workspace your Flex tasks live in. Format: WS followed by 32 hex characters.">Workspace SID</Tooltip>.
* A specific OpenCX session ID (from [Inbox](https://platform.open.cx/inbox)) or the Flex task SID where the problem shows.
* The webhook URL shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Twilio Flex.

<Tip>
  Re-run **Test & Save** in [Settings →
  Integrations](https://platform.open.cx/settings/integrations) → Twilio Flex as
  your first step. Most issues are credential or webhook related.
</Tip>

<Info>
  **Fastest path to root cause:** search the
  [Inbox](https://platform.open.cx/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.
</Info>

## Common scenarios

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

### **"Failed to verify credentials" on save**

<Tooltip tip="Usually caused by a Workspace SID that belongs to a different Twilio account than the Account SID, or an Auth Token that was rotated in the Twilio Console and never re-copied.">
  Likely cause
</Tooltip>

: wrong Workspace SID, or account-level Auth Token mismatch.

**Fix:** re-copy the Account SID and Auth Token from the [Twilio Console](https://console.twilio.com) 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**

<Tooltip tip="Your TaskRouter workflow has a filter for AI tasks but no second filter matching handedOff == true. After OpenCX rejects the AI reservation, the task re-enters the workflow — and if no filter matches, it falls back to the AI queue again.">
  Likely cause
</Tooltip>

: 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**

<Tooltip tip="You only registered the TaskRouter webhook. OpenCX also needs the Conversations service webhook subscribed to onMessageAdded, onConversationAdded, and onParticipantAdded — without it, OpenCX never sees the conversation events that trigger task work.">
  Likely cause
</Tooltip>

: 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**

<Tooltip tip="The webhook URL OpenCX generates embeds your orgId in a signed token. Copying a sandbox webhook URL into a production Twilio account sends production events to your sandbox org — the URL looks valid but carries the wrong identity.">
  Likely cause
</Tooltip>

: a sandbox webhook URL was pasted into a production Twilio account.

**Fix:** copy the webhook URL **freshly** from each environment's [Settings → Integrations](https://platform.open.cx/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 window** | 1 hour (hash of conversation SID + body + send timestamp)                                                                       |
| **Outbound send**                  | Best-effort — retries on transient Twilio failures; does not block handoff on send failure                                      |
| **Flex task closure**              | Customer-side — OpenCX never calls `task.complete()`                                                                            |
| **AI worker provisioning**         | Automatic on first settings save; persists until you delete it in Flex. Scale with **Add AI Agent** in the integration settings |
| **Concurrent chats per AI worker** | 50 (Twilio per-worker cap) — total capacity = workers in the pool × 50                                                          |

<Note>
  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.
</Note>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connect Twilio Flex" icon="plug" href="/integrations/twilio-flex/connect">
    Re-verify credentials, webhooks, and workflow filters.
  </Card>

  <Card title="Handoff and task attributes" icon="user-group" href="/integrations/twilio-flex/handoff">
    Re-verify the task-attribute contract.
  </Card>

  <Card title="Twilio Flex overview" icon="headset" href="/integrations/twilio-flex/overview">
    What Flex lights up across every channel.
  </Card>

  <Card title="Human handoff" icon="user-headset" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>