Skip to main content
You built the action. Here’s what happens on the wire when the AI decides to call it.

​
Path Of A Call

1

Server-side segment filter

Before the AI sees any tools, OpenCX filters the action list by the contact’s segment memberships. An action with an empty Restricted to segments list is visible to every contact; a restricted action reaches only contacts in a matching segment.
2

AI chooses a tool

The AI reads each action’s name and description, matches them against the conversation, and picks zero or one tool per turn. Fuzzy or overlapping descriptions lead to wrong picks — tighten the description if the AI picks an adjacent action.
3

OpenCX calls your API

OpenCX sends an HTTP request from its infrastructure to your endpoint. Headers include User-Agent: OpenCX, any action-level headers, any global variables, any widget-passed headers, and (if enabled) the x-opencx-* context headers. Path and query parameters are filled with values the AI extracted from the conversation.
4

Response back to AI

OpenCX reads the full response body as text and hands it to the AI along with the status code. Keep responses compact — large bodies dilute context and hurt reply quality.
5

Reply to customer

The AI incorporates the response into its reply. For channels like email or SMS, that reply is formatted appropriately before delivery.

​
Timeout And Retries

Value
Timeout per call60 seconds (hard, enforced with AbortSignal.timeout)
Retries on failureNone — OpenCX does not retry
ConcurrencyOne tool call per conversation turn — the AI waits for the response before replying
Circuit breakerNone — every call hits your endpoint
If your endpoint needs longer than 60 seconds, expose a webhook pattern: the action kicks off work and returns a reference ID; a follow-up action (or a workflow) polls by that ID.

​
How The AI Sees Failures

OpenCX returns whatever happened, and the AI decides what to do next — retry, fall back to another action, or hand off to a human.
FailureWhat the AI receives
TimeoutresponseStatus: 408, body Request timed out after 60000ms
Network errorThe string Something went wrong
4xx or 5xxThe upstream status + response body verbatim
SuccessThe 2xx status + response body verbatim
Because the response body is read as plain text, your API should return short, human-readable error messages on 4xx (e.g. "order 12345 not found"). The AI can then explain the failure to the customer in its own words rather than echoing a stack trace.

​
Good To Know

The full body counts against the AI’s context window. Paginate or summarize large lists server-side — return the three most recent orders, not the customer’s entire order history.
OpenCX does not reshape your response. JSON passes through as the raw text the AI reads. If you want pretty-formatted fields in the reply, mirror them in your response payload exactly.
Every action call, including request parameters and response status, is recorded on the conversation session. Open any session in the inbox and expand the tool-call row to audit.

Build An Action

The fields that decide what the AI sees.

Authentication

Where each header comes from at call time.

Troubleshooting

When the call doesn’t land as expected.

Human Handoff

What happens when the AI gives up after a failed action.