OpenAPI Import

If your product already exposes an OpenAPI spec, you can generate one OpenCX action per operation instead of authoring each by hand.

Import replaces every action previously generated from your spec. Hand-authored actions in the dashboard are left alone. If you mix both, keep hand-authored actions in a clearly separate naming convention.

What OpenCX Accepts

	Value
OpenAPI versions	2.0, 3.0, 3.1
File format	JSON or YAML
Base URL	Read from `servers[0].url`, or you can override at import time
Auth	Operations call out auth in the spec, but secrets live in global variables — see Authentication
Default channel	Imported actions are enabled on the widget channel only; toggle others from the action’s page

Custom Extensions

OpenCX reads three vendor extensions to pre-configure each action:

Extension	Effect
`x-open-require-form-submission`	When `true`, the AI pauses on a form the customer must submit before the call
`x-open-pinned`	When `true`, the action is pinned at the top of the dashboard list
`x-open-tags`	Array of tag strings applied to the action for dashboard filtering

Drop these at the operation level:

paths:
  /orders/{order_id}:
    get:
      operationId: getOrder
      summary: Look up an order by ID
      x-open-tags: ['orders', 'support']
      x-open-pinned: true

Upload

From the dashboard
From CI

Go to Actions, click Import from OpenAPI, and pick your spec.json or spec.yaml. Watch the actions list for new rows. If validation fails, the dashboard surfaces the first invalid operation — fix and re-upload.

Use the public API endpoint PUT https://api.open.cx/actions/import with a multipart file upload. Auth is a bearer API key with the actions:write scope — generate one under Settings → Access. See API authentication.

GitHub Actions

name: Sync OpenCX actions

on:
  push:
    branches: [main]
    paths:
      - 'openapi.yaml'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Push spec to OpenCX
        env:
          OPENCX_TOKEN: ${{ secrets.OPENCX_API_TOKEN }}
        run: |
          curl --fail-with-body \
            -X PUT https://api.open.cx/actions/import \
            -H "Authorization: Bearer $OPENCX_TOKEN" \
            -F "[email protected]"

GitLab CI

sync-opencx-actions:
  image: curlimages/curl:latest
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - openapi.yaml
  script:
    - |
      curl --fail-with-body \
        -X PUT https://api.open.cx/actions/import \
        -H "Authorization: Bearer $OPENCX_API_TOKEN" \
        -F "[email protected]"

The import runs in a single transaction — old actions generated from your previous spec are soft-deleted and new ones inserted atomically. No separate cleanup step is needed.

What Fails And Why

Error	What it means	Fix
`failed_to_parse_spec`	The file isn’t valid OpenAPI or the format doesn’t match the extension	Run your spec through a validator; confirm JSON vs YAML
`invalid_tool_schema`	One operation uses schema features the AI tool-call validator rejects (deeply nested `oneOf`, circular refs, non-JSON-Schema types)	Simplify the offending operation, remove custom types, re-upload
`cannot_determine_api_endpoint`	No `servers[0].url` in the spec and no override passed	Add a `servers` block, or send `serverBaseUrl` with the API call

Build An Action

Hand-author a single action from the dashboard form.

Authentication

Where secrets live for imported actions.

Execution

Timeout, retries, response handling.

Troubleshooting

Import errors and post-import failures.

Overview

AI Chat Widget

AI WhatsApp Support

AI SMS Support

AI Phone Support

AI Email Support

AI Actions

Resources

What OpenCX Accepts

Custom Extensions

Upload

GitHub Actions

GitLab CI

What Fails And Why

Build An Action

Authentication

Execution

Troubleshooting

Overview

AI Chat Widget

AI WhatsApp Support

AI SMS Support

AI Phone Support

AI Email Support

AI Actions

Resources

​What OpenCX Accepts

​Custom Extensions

​Upload

​GitHub Actions

​GitLab CI

​What Fails And Why

​Related Documentation

Build An Action

Authentication

Execution

Troubleshooting

What OpenCX Accepts

Custom Extensions

Upload

GitHub Actions

GitLab CI

What Fails And Why

Related Documentation