> ## 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.

# Execution

> How an action call runs end to end — when the AI picks a tool, what reaches your API, the 60-second timeout, and how failures get back to the AI.

You built the action. Here's what happens on the wire when the AI decides to call it.

## Path Of A Call

```mermaid theme={"dark"}
flowchart LR
  A([Customer message]) --> B[Filter by segment]
  B --> C[AI picks a tool]
  C --> D[OpenCX calls your API]
  D --> E[Response back to AI]
  E --> F([Reply to customer])

  style A fill:#1a5c20,color:#fff,stroke:#267a2e
  style F fill:#1a5c20,color:#fff,stroke:#267a2e
```

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Reply to customer">
    The AI incorporates the response into its reply. For channels like email or SMS, that reply is formatted appropriately before delivery.
  </Step>
</Steps>

## Timeout And Retries

|                        | Value                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------- |
| **Timeout per call**   | 60 seconds (hard, enforced with `AbortSignal.timeout`)                              |
| **Retries on failure** | None — OpenCX does not retry                                                        |
| **Concurrency**        | One tool call per conversation turn — the AI waits for the response before replying |
| **Circuit breaker**    | None — 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.

| Failure           | What the AI receives                                          |
| ----------------- | ------------------------------------------------------------- |
| **Timeout**       | `responseStatus: 408`, body `Request timed out after 60000ms` |
| **Network error** | The string `Something went wrong`                             |
| **4xx or 5xx**    | The upstream status + response body verbatim                  |
| **Success**       | The 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

<AccordionGroup>
  <Accordion title="Response-body size matters" icon="weight-scale">
    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.
  </Accordion>

  <Accordion title="Bodies don't transform" icon="arrow-right-arrow-left">
    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.
  </Accordion>

  <Accordion title="Per-call logging lives on the session" icon="microscope">
    Every action call, including request parameters and response status, is recorded on the conversation session. Open any session in the [inbox](https://platform.open.cx/inbox) and expand the tool-call row to audit.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Build An Action" icon="plug" href="/actions/build-an-action">
    The fields that decide what the AI sees.
  </Card>

  <Card title="Authentication" icon="shield-halved" href="/actions/authentication">
    Where each header comes from at call time.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/actions/troubleshooting">
    When the call doesn't land as expected.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    What happens when the AI gives up after a failed action.
  </Card>
</CardGroup>