Skip to main content
OpenCX does not replace your TaskRouter workflow — it participates in it as one more worker. This page describes exactly what OpenCX writes to a Flex task on handoff, what your workflow is expected to do with it, and the one thing OpenCX explicitly does not do (close the task).

​
How handoff works

When a handoff fires, OpenCX runs these steps in order:
1

Update the Flex task attributes

OpenCX writes the handoff fields (see the table below) into the task’s attributes JSON via TaskRouter’s API. Any attributes your workflow already set on the task are preserved.
2

Reject the AI reservation

The is rejected. The task is now eligible for re-routing.
3

Workflow re-routes

TaskRouter re-evaluates the task against your workflow filters. The handedOff == true filter matches, and the task is assigned to your human queue.
4

Handoff note posts to the conversation

OpenCX posts a short system message into the Flex conversation with the summary, sentiment, and reason, so the rep who picks up sees it above their first reply.

​
What OpenCX writes to the task

AttributeTypePurpose
handedOffbooleanAlways true. The filter your workflow keys on.
handoffReasonstringShort phrase the AI wrote when escalating — e.g. “customer wants to cancel subscription”.
handoffSummarystringOne-paragraph summary of the conversation so far.
handoffSentimentstringDetected sentiment — positive, neutral, or negative.
handoffLanguagestringBCP-47 language code of the conversation — e.g. en, es, ar.
handoffTimestampISO 8601 stringWhen the handoff fired.
OpenCX only adds these attributes. Every other attribute on the task — whatever your workflow set during routing — stays untouched.

​
What the rep sees in Flex

  • The task in their queue with the six handoff attributes above, visible in the Task panel of the Flex UI.
  • A system message at the top of the Flex conversation thread: the summary, sentiment, and reason formatted for human reading.
  • The full above the handoff note — no replay, no separate tab.
  • Any flex_* custom data the workflow set during routing (see below) preserved on the task.
The AI’s replies appear in the conversation as author AI Support Agent, so the rep can distinguish them from the customer’s own messages.

​
Using Flex attributes in Autopilot

Every attribute your Flex workflow attaches to a task is flattened onto the OpenCX session’s custom_data with a flex_ prefix. Autopilot actions read from custom_data directly — no extra mapping.
A Flex attribute named order_id becomes flex_order_id on the session. Nested attributes are flattened with underscores — customer.name becomes flex_customer_name. The flattening happens on every task event, so late-arriving attributes show up without you re-running anything.
Teams commonly set order_id, user_id, city, zone, or tier tags on the task. Any of these show up as flex_order_id, flex_user_id, etc., and can be used in an .
OpenCX does not define which attributes exist — your Flex workflow does. The only guarantee is the flex_ prefix. If you rename an attribute on the Flex side, update your Autopilot conditions to match.

​
Closing Flex tasks

OpenCX does not close Flex tasks. When the AI resolves or hands off, OpenCX only marks its own session state and rejects the reservation — it never calls task.complete() or sets assignmentStatus: 'completed'. Closing the Flex task is your rep’s or your workflow’s responsibility.
If you want tasks to close automatically on AI resolution:
  • Add a TaskRouter event callback on task.wrapup or reservation.wrapup and close via your own automation.
  • Or configure a Flex workflow rule that closes tasks whose AI reservation was rejected without a successor assignment — depending on how your queues are structured.
Treat this as product parity with your existing Flex task lifecycle, not as something OpenCX overrides.

Connect Twilio Flex

Credentials, webhook registration, workflow filters.

Channels

Per-channel implementation on top of this shared setup.

Autopilot topics

Read flex_* custom_data in topic conditions and actions.

Troubleshooting

Handoff fires but the task stays in the AI queue, and other scenarios.