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