Actions troubleshooting

Before debugging, have these ready: the action name, a session ID where it should have been called, and the endpoint you expect to receive traffic.

Looking for setup? See Build an action. For the runtime model, see Execution.

Common Troubleshooting Scenarios

Symptom	Likely cause	What to do
OpenAPI import fails with `invalid_tool_schema`	One operation uses schema features the AI tool validator rejects — nested `oneOf`, circular `$ref`, non-JSON-Schema types	Simplify the offending operation, flatten `oneOf`, resolve circular refs, re-upload. See OpenAPI import.
Endpoint returns 401 / 403 but Test works	The Test call injects placeholder `x-opencx-*` context headers; your production middleware blocks them, or your bearer-token casing differs between the Test payload and the saved global variable	Allow `x-opencx-` through your WAF. Confirm the global variable value matches the full* `Authorization` string, including any `Bearer` prefix.
Test passes but the production call never lands	CORS (widget path only), firewall / IP allowlist, or provider-side rate limit on your production endpoint	Add OpenCX egress IPs to your allowlist — ask support for the current list. Check CORS for widget-initiated calls. Inspect your API gateway for rate-limit denials.
AI doesn’t call the action at all	Channel toggle off, segment restriction excludes this contact, or the description is too vague for the AI to match intent	Enable the channel on the action’s page. Verify the contact’s segment memberships. Sharpen the description to name the noun + verb (e.g. “look up an order by ID and return tracking details”).
None of the above	—	Capture the session ID and action name, contact support.

OpenCX enforces a 60-second timeout and does not retry. Failures return to the AI as status codes or a short error string — see Execution for the exact failure shapes.

Limits Recap

	Value
Request timeout	60 seconds (no retries)
Transport	HTTPS only
Supported methods	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`
Body formats	JSON, `multipart/form-data`

Impact Of Misconfiguration

Misconfigured actions fail silently from the customer’s point of view — the AI either calls the wrong endpoint, gets an error and covers with a generic fallback, or skips the action entirely and hands off. None of these show up as a red banner in the dashboard. Always verify in a real conversation after changing an action’s endpoint, description, or segment restriction.

Build An Action

Re-check fields, magic values, and the Test button.

Execution

Re-check timeout, headers, and response handling.

Authentication

Global variables, widget headers, context headers.

Human Handoff

What happens when repeated action failures escalate.

Overview

AI Chat Widget

AI WhatsApp Support

AI SMS Support

AI Phone Support

AI Email Support

AI Actions

Resources

Actions troubleshooting

Common Troubleshooting Scenarios

Limits Recap

Impact Of Misconfiguration

Build An Action

Execution

Authentication

Human Handoff

​Common Troubleshooting Scenarios

​Limits Recap

​Impact Of Misconfiguration

​Related Documentation

Build An Action

Execution

Authentication

Human Handoff

Common Troubleshooting Scenarios

Limits Recap

Impact Of Misconfiguration

Related Documentation