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

# Build An Action

> Create an HTTP action in the OpenCX dashboard — name, endpoint, parameters, headers, test, and enable on a channel.

Build an action once, reuse it everywhere the AI runs. You author each action from **[Actions](https://platform.open.cx/actions)** in your [OpenCX dashboard](https://platform.open.cx).

## Prerequisites

* An **endpoint** the AI can reach over HTTPS. OpenCX does not call `http://` URLs.
* A **description** of what the endpoint does — the AI reads it to decide when to call.
* Any **credentials** the endpoint expects. See [Authentication](/actions/authentication) for where secrets live.

## Create The Action

<Steps>
  <Step title="Open the form">
    Go to **[Actions → New action](https://platform.open.cx/actions/new)**.
  </Step>

  <Step title="Name and description">
    **Name** (minimum 5 characters) and **Description** (minimum 20 characters) are both required. The AI reads them together to decide whether the customer's request matches this action — treat the description as prompt, not internal notes.

    Good: *"Look up an order by its numeric order ID and return shipping status, carrier, and tracking number."*
    Bad: *"Order stuff."*
  </Step>

  <Step title="Method and endpoint">
    Pick the HTTP **Method** (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) and paste the full **API Endpoint** URL. For path parameters, use curly braces — for example `https://api.acme.com/orders/{order_id}`. The AI fills `order_id` from the conversation.
  </Step>

  <Step title="Body (JSON)">
    For `POST` / `PUT` / `PATCH`, paste a JSON schema describing the body. If you don't have a schema, paste a sample JSON object and OpenCX infers the schema. Each field becomes a parameter the AI extracts from the conversation.
  </Step>

  <Step title="Headers and parameters">
    Add static **Headers** (e.g. `Content-Type: application/json`) and per-call **Parameters** (query or path). Each row has a **Key** and **Value**.

    Click the wand icon on a value to turn it into a <Tooltip tip="A value OpenCX fills in at call time from conversation context — contact email, session ID, channel, etc. — instead of a hard-coded string.">magic field</Tooltip>. Magic fields are filled from conversation context automatically, so the AI doesn't need to guess them.
  </Step>

  <Step title="Segment restrictions">
    By default every action is visible to every contact. To restrict — for example a refund action only VIPs should trigger — pick one or more [segments](https://platform.open.cx/contacts) under **Restricted to segments**. OpenCX filters the tool list on the server before the AI sees it, so restricted actions never reach unauthorized contacts.
  </Step>

  <Step title="Enable on channels">
    Toggle the channels the AI can use this action on — widget, email, SMS, WhatsApp, phone, Slack. A brand-new action defaults to widget only.
  </Step>

  <Step title="Test">
    Click **Test** to send a sample request with placeholder context headers and your saved global variables. A 2xx response means the HTTP contract works.

    <Warning>
      **Test proves the HTTP call works — not that the AI will pick it.** Production firewalls, CORS, rate limits, and IP allowlists still apply. Always verify in a real conversation after enabling on a channel.
    </Warning>
  </Step>
</Steps>

## Limits

|                          | Value                                                |
| ------------------------ | ---------------------------------------------------- |
| **Request timeout**      | 60 seconds — no retries                              |
| **Supported methods**    | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`              |
| **Transport**            | HTTPS only                                           |
| **Body formats**         | JSON, `multipart/form-data`                          |
| **Path parameters**      | `{curly_braces}` in the URL                          |
| **Magic fields**         | Available on both header values and parameter values |
| **Per-org action count** | No hard limit today                                  |

## Good To Know

<AccordionGroup>
  <Accordion title="Rename an endpoint without rebuilding the action" icon="wand-magic-sparkles">
    Only the URL and method are referenced at call time — you can change either without re-authoring parameters. Description changes take effect on the next conversation turn.
  </Accordion>

  <Accordion title="Require an inline form before the call" icon="clipboard-list">
    Some actions need explicit customer confirmation — address changes, refunds, cancellations. The **Require form submission** toggle pauses the AI on a filled-in form the customer must submit before the call goes out.
  </Accordion>

  <Accordion title="When the description is ambiguous" icon="circle-question">
    If two actions have overlapping names or descriptions, the AI may pick the wrong one. Sharpen the description to include the **noun** (order, account, subscription) and the **verb** (look up, cancel, update). Avoid generic names like `get_data`.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield-halved" href="/actions/authentication">
    Where secrets live, how headers reach your API.
  </Card>

  <Card title="OpenAPI Import" icon="file-import" href="/actions/openapi-import">
    Bulk-author from a spec, keep in sync from CI.
  </Card>

  <Card title="Execution" icon="diagram-project" href="/actions/execution">
    Timeout, retries, response handling, failure modes.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/actions/troubleshooting">
    Common failure patterns and fixes.
  </Card>
</CardGroup>