Skip to main content
Build an action once, reuse it everywhere the AI runs. You author each action from Actions in your OpenCX dashboard.

​
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 for where secrets live.

​
Create The Action

1

Open the form

Go to Actions → New action.
2

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.”
3

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

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

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 . Magic fields are filled from conversation context automatically, so the AI doesn’t need to guess them.
6

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 under Restricted to segments. OpenCX filters the tool list on the server before the AI sees it, so restricted actions never reach unauthorized contacts.
7

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

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

​
Limits

Value
Request timeout60 seconds — no retries
Supported methodsGET, POST, PUT, PATCH, DELETE
TransportHTTPS only
Body formatsJSON, multipart/form-data
Path parameters{curly_braces} in the URL
Magic fieldsAvailable on both header values and parameter values
Per-org action countNo hard limit today

​
Good To Know

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

Authentication

Where secrets live, how headers reach your API.

OpenAPI Import

Bulk-author from a spec, keep in sync from CI.

Execution

Timeout, retries, response handling, failure modes.

Troubleshooting

Common failure patterns and fixes.