# AUTHORING
Source: https://docs.open.cx/AUTHORING



# Docs authoring spec

Everything here is enforced by `pnpm lint-frontmatter`. A PR that touches any `.mdx` under `docs/` fails CI if the changed files don't conform.

Mintlify's built-in search ranks pages on four signals: `title`, `description`, `keywords`, and body text. Getting the first three right is the difference between "users find what they need in one search" and "users give up and open a support ticket". Treat frontmatter as a search surface, not metadata.

## Required frontmatter

Every page — content pages and API reference alike — must ship this frontmatter:

```yaml theme={"dark"}
---
title: 'Zendesk overview'
sidebarTitle: 'Overview'
description: 'Run Zendesk as the surface your agents work in while OpenCX resolves, routes, and grounds every conversation in your Help Center.'
icon: 'ticket'
keywords:
  - zendesk
  - zendesk integration
  - zendesk handoff
  - connect zendesk
  - zd tickets
  - help center sync
  - sunshine conversations
  - zendesk 401
---
```

### `title` — unique, descriptive

* **Never** a bare word from this denylist: `Overview`, `Troubleshooting`, `Connect`, `Index`, `Introduction`, `Get started`, `Configuration`, `Setup`.
* Format: `<Product or Feature> <Page type>` — e.g. `Zendesk overview`, `Notion troubleshooting`, `Shopify connect`, `Voice agent introduction`.
* The title is what Mintlify's search results show. Two pages titled `Overview` are indistinguishable to a searching user.
* Use `sidebarTitle` if you want the sidebar to stay short (`Overview`); it doesn't affect search ranking.

### `description` — 120–160 chars, "what + when"

* Answer two questions: *what does this page do* and *when should I read it*.
* Example: `Connect Zendesk as a knowledge source to sync help center articles and tickets into OpenCX agents. Use when onboarding an existing Zendesk account.`
* Shows up in search results underneath the title and as the `<meta description>` for SEO.
* Hard lint range: 80–200 chars. Target range: 120–160.

### `keywords` — 8–15 entries, four categories

Pick from these buckets — at least one entry from each of the first three:

1. **Product / aliases (2–3)** — product name + common abbreviations or misspellings. `zendesk`, `zd`, `zen desk`.
2. **Task phrases (2–3)** — verbs a user would type. `connect zendesk`, `sync zendesk tickets`, `zendesk oauth`.
3. **Synonyms (2–3)** — alternate terminology. `help desk integration`, `ticket sync`, `zendesk crm`.
4. **Error / failure terms (1–2, when relevant)** — symptoms users search when something breaks. `zendesk 401`, `subdomain invalid`, `token expired`.

Rules of thumb:

* **Don't duplicate keywords from a parent page.** If `integrations/zendesk/overview.mdx` already owns `zendesk integration`, don't repeat it on `integrations/zendesk/channels/email.mdx` — that page should own `zendesk email`, `zendesk email channel`, etc.
* **Don't over-keyword.** More than 20 entries dilutes ranking.
* **Use phrases, not single words, for specificity.** `zendesk email` beats `email` in a large corpus.
* **Mirror real user language.** Steal phrasing from support tickets, Slack questions, competitor docs.

## Author PR checklist

Paste into your PR description:

* [ ] `title` unique and descriptive (not bare `"Overview"` / `"Troubleshooting"`)
* [ ] `description` 120–160 chars, answers *what + when*
* [ ] `keywords` 8–15 entries with ≥1 alias, ≥1 task phrase, ≥1 synonym
* [ ] Searched the page title + 2 alternate phrases in `pnpm dev` and confirmed top-3 ranking
* [ ] No keyword overlap with parent / sibling pages that would dilute ranking

## Tools

* `pnpm dev` — run Mintlify locally on port 3009 and test search interactively.
* `pnpm lint-frontmatter` — runs the frontmatter lint. Fails on missing title/description/keywords, denylisted titles, and out-of-range description lengths.
* `pnpm lint-frontmatter:fix` — auto-patches trivially-fixable cases (e.g. adds `sidebarTitle` when rewriting `title`).
* `pnpm suggest-frontmatter -- <path/to/file.mdx>` — prints a suggested keyword set and rewritten title for one page.
* `pnpm suggest-frontmatter -- --missing-only` — lists every file currently missing `keywords`.
* `pnpm enrich-api-stubs -- <path/to/api-reference/xxx.mdx>` — fills in a stub API page from the OpenAPI spec.
* `pnpm benchmark-search` — runs the 25-query benchmark against `http://localhost:3009` and prints a scorecard.

## Opt-out

For the rare page where the rules genuinely don't apply (landing page, coming-soon stub), add this comment as the very first line of the MDX body (after the closing `---`):

```mdx theme={"dark"}
{/* lint-frontmatter-disable: <one-line reason> */}
```

Use sparingly. The lint output lists every opt-out so they stay visible.


# Authentication
Source: https://docs.open.cx/actions/authentication

Secure action calls — store org-wide secrets as global variables or named secrets, pass per-user tokens from the widget, and rely on context headers OpenCX attaches automatically.

Your action endpoint decides who's allowed to call it. OpenCX gives you four ways to reach that decision — pick one or combine them.

## The Four Paths

| Path | Use it for | Where it lives |
| - | - | - |
| **Named secrets** | A credential one action (or a few) needs — referenced per header, sent only where you put it | [Settings → Secrets](https://platform.open.cx/settings) |
| **Global variables** | Credentials every customer shares — a server-to-server API key, a signing secret | [Settings → Variables](https://platform.open.cx/settings) |
| **Widget headers** | Credentials that differ per customer — a session token, a per-user JWT | Your frontend, passed to the widget at init |
| **Context headers** | Identifying the OpenCX-side session / org / contact to your API | Attached automatically by OpenCX |

## Named Secrets

Define a credential once, then reference it from any action header as `{{secrets.<name>}}` — or pick it from the header editor's secret picker. Unlike global variables, a secret is sent **only** on the requests whose headers reference it, so one workspace can talk to many upstream systems without every call carrying every key.

Values are **write-only**: encrypted at rest, never returned by any API or screen after creation, and decrypted only at the moment a request actually fires. Forgot a value? Type a replacement — there is no way to read the old one back. MCP server auth headers accept the same `{{secrets.<name>}}` references.

<Steps>
  <Step title="Create the secret">
    Go to **[Settings → Secrets](https://platform.open.cx/settings)**, choose a name, paste the value. The name is permanent — actions reference secrets by name.
  </Step>

  <Step title="Reference it from a header">
    In the action's header editor, set the value to `{{secrets.<name>}}` or use the picker. A header whose secret is missing is dropped, never sent raw.
  </Step>
</Steps>

## Global Variables

Store once, OpenCX injects the value into every action call for your organization. Values are **encrypted at rest** and **decrypted per request**.

<Steps>
  <Step title="Open the variables page">
    Go to **[Settings → Variables](https://platform.open.cx/settings)**.
  </Step>

  <Step title="Add a variable">
    Set a **key** and **value**. The key becomes the HTTP header name on every outbound action call.
  </Step>

  <Step title="Reference from an action">
    Nothing further to wire up — any action whose endpoint sits behind that header will authenticate.
  </Step>
</Steps>

<Note>
  Use a full `Authorization` header value (e.g. `Bearer <token>`) when your API expects Bearer auth — OpenCX sends the value verbatim, it does not prepend `Bearer `.
</Note>

## Widget Headers

Pass per-user credentials from your frontend at widget-init time. OpenCX uses them only for that contact's action calls and does not persist them.

```javascript theme={"dark"}
const options = {
  token: 'YOUR_COPILOT_TOKEN',
  headers: {
    Authorization: `Bearer ${userJwt}`,
  },
};
```

Widget headers **override** same-named global variables for that contact's session. Use this when each signed-in customer needs their own scoped token.

## Context Headers

When your org has context headers enabled, OpenCX adds four identifying headers to every action call:

| Header | Value |
| - | - |
| `x-opencx-org-id` | Your organization UUID |
| `x-opencx-session-id` | The conversation session UUID — the trace key |
| `x-opencx-ticket-number` | Numeric ticket ID for the session |
| `x-opencx-external-user-id` | The contact's external ID if they're authenticated |

Your API can use these to:

* **Trace** an action call back to a specific conversation in the [OpenCX inbox](https://platform.open.cx/inbox) — the session ID is a clickable link.
* **Rate-limit** per org without customers passing their own org ID as a parameter.
* **Scope** responses — e.g. return a contact's orders based on `x-opencx-external-user-id` instead of trusting a query parameter the AI extracted.

<Note>
  Context headers are opt-in at the org level. If you need them on, ask support to enable automatic action headers for your org.
</Note>

Every action call also carries `User-Agent: OpenCX` so your firewall and logs can filter.

## Choosing A Path

| Situation | Path |
| - | - |
| Every customer hits the same backend with the same server-to-server key | **Global variable** |
| Each signed-in customer has their own scoped token | **Widget header** (with a global variable for any shared service-account header) |
| Your API needs to know which OpenCX session / org / contact made the call | **Context headers** |

## Security Best Practices

<AccordionGroup>
  <Accordion title="Validate context headers server-side" icon="lock-keyhole">
    Treat `x-opencx-org-id` as a signal, not a credential — pair it with a global-variable shared secret your API also checks. That way a leaked URL alone can't forge OpenCX traffic.
  </Accordion>

  <Accordion title="Don't log full header values" icon="eye-slash">
    Redact anything matching `Authorization`, `*-Token`, `*-Key` in your access logs. OpenCX does not replay headers, but your own log pipeline and dashboards can.
  </Accordion>

  <Accordion title="HTTPS only" icon="shield-check">
    OpenCX refuses to call `http://` URLs. If your endpoint isn't behind TLS today, put it behind a gateway that is.
  </Accordion>

  <Accordion title="Rotate secrets without losing conversations" icon="arrows-rotate">
    Update the global variable value — no action edit needed. Existing in-flight tool calls finish against the old value; the next call uses the new one.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Build An Action" icon="plug" href="/actions/build-an-action">
    Form fields, headers, parameters, test.
  </Card>

  <Card title="Execution" icon="diagram-project" href="/actions/execution">
    How headers reach your API at call time.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/actions/troubleshooting">
    401s, 403s, and signal-header gotchas.
  </Card>

  <Card title="Widget Authentication" icon="user-lock" href="/widget/authentication">
    Full widget auth model including identity verification.
  </Card>
</CardGroup>


# Build An Action
Source: https://docs.open.cx/actions/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**.

    Keep identifiers that stay the same on every call, such as an account ID, as fixed query or path parameter values. Leave customer-specific inputs, such as an order reference, dynamic. When managing actions through the API, fixed values are stored in `payload.parameters[].value`; preserve them when [updating an action](/api-reference/actions/update).

    Click the wand icon on a value to turn it into a <Tooltip>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, Instagram, Messenger, X (Twitter), phone, Slack, and more. 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. Once enabled, the requirement stays enabled when you edit other action settings; turn the toggle off explicitly to remove it.
  </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>
  <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>


# Execution
Source: https://docs.open.cx/actions/execution

How an action call runs end to end — when the AI picks a tool, what reaches your API, the 60-second timeout, and how failures get back to the AI.

You built the action. Here's what happens on the wire when the AI decides to call it.

## Path Of A Call

```mermaid theme={"dark"}
flowchart LR
  A([Customer message]) --> B[Filter by segment]
  B --> C[AI picks a tool]
  C --> D[OpenCX calls your API]
  D --> E[Response back to AI]
  E --> F([Reply to customer])

  style A fill:#1a5c20,color:#fff,stroke:#267a2e
  style F fill:#1a5c20,color:#fff,stroke:#267a2e
```

<Steps>
  <Step title="Server-side segment filter">
    Before the AI sees any tools, OpenCX filters the action list by the contact's segment memberships. An action with an empty **Restricted to segments** list is visible to every contact; a restricted action reaches only contacts in a matching segment.
  </Step>

  <Step title="AI chooses a tool">
    The AI reads each action's **name** and **description**, matches them against the conversation, and picks zero or one tool per turn. Fuzzy or overlapping descriptions lead to wrong picks — tighten the description if the AI picks an adjacent action.
  </Step>

  <Step title="OpenCX calls your API">
    OpenCX sends an HTTP request from its infrastructure to your endpoint. Headers include `User-Agent: OpenCX`, any action-level headers, any global variables, any widget-passed headers, and (if enabled) the `x-opencx-*` context headers. Path and query parameters are filled with values the AI extracted from the conversation.
  </Step>

  <Step title="Response back to AI">
    OpenCX reads the full response body as text and hands it to the AI along with the status code. Keep responses compact — large bodies dilute context and hurt reply quality.
  </Step>

  <Step title="Reply to customer">
    The AI incorporates the response into its reply. For channels like email or SMS, that reply is formatted appropriately before delivery.
  </Step>
</Steps>

## Timeout And Retries

| | Value |
| - | - |
| **Timeout per call** | 60 seconds (hard, enforced with `AbortSignal.timeout`) |
| **Retries on failure** | None — OpenCX does not retry |
| **Concurrency** | One tool call per conversation turn — the AI waits for the response before replying |
| **Circuit breaker** | None — every call hits your endpoint |

If your endpoint needs longer than 60 seconds, expose a webhook pattern: the action kicks off work and returns a reference ID; a follow-up action (or a workflow) polls by that ID.

## How The AI Sees Failures

OpenCX returns whatever happened, and the AI decides what to do next — retry, fall back to another action, or hand off to a human.

| Failure | What the AI receives |
| - | - |
| **Timeout** | `responseStatus: 408`, body `Request timed out after 60000ms` |
| **Network error** | The string `Something went wrong` |
| **4xx or 5xx** | The upstream status + response body verbatim |
| **Success** | The 2xx status + response body verbatim |

Because the response body is read as plain text, your API should return short, human-readable error messages on 4xx (e.g. `"order 12345 not found"`). The AI can then explain the failure to the customer in its own words rather than echoing a stack trace.

## Good To Know

<AccordionGroup>
  <Accordion title="Response-body size matters" icon="weight-scale">
    The full body counts against the AI's context window. Paginate or summarize large lists server-side — return the three most recent orders, not the customer's entire order history.
  </Accordion>

  <Accordion title="Bodies don't transform" icon="arrow-right-arrow-left">
    OpenCX does not reshape your response. JSON passes through as the raw text the AI reads. If you want pretty-formatted fields in the reply, mirror them in your response payload exactly.
  </Accordion>

  <Accordion title="Per-call logging lives on the session" icon="microscope">
    Every action call, including request parameters and response status, is recorded on the conversation session. Open any session in the [inbox](https://platform.open.cx/inbox) and expand the tool-call row to audit.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Build An Action" icon="plug" href="/actions/build-an-action">
    The fields that decide what the AI sees.
  </Card>

  <Card title="Authentication" icon="shield-halved" href="/actions/authentication">
    Where each header comes from at call time.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/actions/troubleshooting">
    When the call doesn't land as expected.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    What happens when the AI gives up after a failed action.
  </Card>
</CardGroup>


# AI Actions
Source: https://docs.open.cx/actions/introduction

Let the AI do real work in your systems mid-conversation — look up orders, file tickets, update accounts, trigger workflows — instead of only replying with text.

A customer asks "where's my order?". The AI calls your order-lookup endpoint, reads the status from the response, and replies with the real tracking number. That's an **action** — an HTTP call the AI decides to make, authored by you in the [OpenCX dashboard](https://platform.open.cx/actions).

<Tip>
  Ready to build? Skip to **[Build an action](/actions/build-an-action)**.
</Tip>

## Core Capabilities

<AccordionGroup>
  <Accordion title="The AI decides when to call" icon="robot">
    Actions are not keyword-triggered. The AI reads the action's **name** and **description** to decide whether the customer's request matches, then fills in parameters from the conversation. Write the description like you'd write a Jira ticket for a teammate — "look up the order status and return tracking details for a given order ID."
  </Accordion>

  <Accordion title="Scoped to who's asking" icon="user-shield">
    Each action can be restricted to one or more contact segments. A refund action visible only to VIP customers, an internal-account-tools action visible only to staff contacts — all filtered on the server before the AI sees the tool list.
  </Accordion>

  <Accordion title="Works on every channel" icon="grid-2">
    Once an action is enabled on a channel, it's available there — widget, email, SMS, WhatsApp, Instagram, Messenger, X (Twitter), phone, Slack, and more. No per-channel re-authoring.
  </Accordion>

  <Accordion title="Author one at a time or bulk from OpenAPI" icon="file-import">
    Build an action from the dashboard form, or upload an OpenAPI spec and generate one action per operation. CI pipelines can push spec changes automatically. See [OpenAPI import](/actions/openapi-import).
  </Accordion>
</AccordionGroup>

## Where Actions Fit

OpenCX exposes four kinds of tools to the AI. This doc set covers the first two.

| Kind | Who authors it | Lives where |
| - | - | - |
| **HTTP actions** | You, in the [OpenCX dashboard](https://platform.open.cx/actions) | This doc set |
| **MCP server tools** | An external MCP server you connect | [MCP servers](/actions/mcp-servers) |
| **Integration actions** | Built in per integration (e.g. [Shopify AI Actions](/integrations/shopify/ai-actions)) | Under the relevant integration page |
| **System actions** | Built-in capabilities (human handoff, send email, collect input, auto-resolve) | No configuration — always available |

## Next Step

<Card title="Build your first action" icon="plug" href="/actions/build-an-action">
  Name, endpoint, parameters, test, enable on a channel.
</Card>

***

## Related Documentation

<CardGroup>
  <Card title="Build An Action" icon="plug" href="/actions/build-an-action">
    Dashboard form, fields, test button, channel enablement.
  </Card>

  <Card title="MCP Servers" icon="plug-circle-bolt" href="/actions/mcp-servers">
    Connect an external MCP server and use its tools as actions.
  </Card>

  <Card title="Authentication" icon="shield-halved" href="/actions/authentication">
    Global variables, per-user headers, automatic context headers.
  </Card>

  <Card title="Execution" icon="diagram-project" href="/actions/execution">
    How a call runs — timeout, retries, response handling.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/actions/troubleshooting">
    Import failures, 401s, test-passes-prod-fails, AI not calling.
  </Card>
</CardGroup>


# MCP Servers
Source: https://docs.open.cx/actions/mcp-servers

Connect an external MCP server so its tools become AI actions — OAuth or header auth, per-tool opt-out, and a preset gallery for Slack, HubSpot, Notion, and more.

<Info>
  **Beta.** MCP servers are available now, but the surface is still settling — expect changes.
</Info>

Instead of authoring one HTTP action per endpoint, point OpenCX at an MCP server and every tool it publishes becomes available to your AI agents. Useful for vendors that already ship a remote MCP server — Slack, HubSpot, Notion, Stripe — where hand-authoring each operation as a separate action would just be re-describing their own tool definitions.

## Connect a Server

Go to **[Actions](https://platform.open.cx/actions)** and add a server from the **MCP servers** section — either pick one from the preset gallery (OpenCX, Slack, HubSpot, Intercom, Linear, Notion, Stripe) or add a custom URL.

<Steps>
  <Step title="Enter the server URL">
    A Streamable HTTP or SSE endpoint, e.g. `https://mcp.example.com/mcp`. OpenCX probes it to detect how it authenticates.
  </Step>

  <Step title="Choose who connects">
    Select **Our team — one shared account** to connect from Actions, or **Each user — their own account** to let signed-in widget customers connect individually. Ownership is fixed when the server is created.
  </Step>

  <Step title="Authenticate">
    For a shared account, authenticate here. For personal accounts, follow [Widget connections](/widget/connections) to authenticate your customers and let them connect inside the widget.

    * **OAuth** — if the server advertises OAuth (discovery + dynamic client registration), OpenCX opens its authorization page. Approve, and you're redirected back connected. Tokens are refreshed automatically and kept out of the widget. Personal connections can optionally be [reused by your backend](/widget/authentication#reuse-a-customer-connection-in-your-backend).
    * **Request headers** — if the server expects a static credential instead (an API key, a bearer token), enter it as a header. Values are encrypted at rest and never displayed again; reference a [named secret](/actions/authentication#named-secrets) instead of pasting a raw value so the credential lives in one place.

    <Note>
      Slack's MCP server supports neither automatic path, so it uses a pre-registered OAuth client instead of discovery.
    </Note>
  </Step>

  <Step title="Review and enable">
    Once connected, OpenCX lists every tool the server publishes. The server is enabled by default — flip it off to keep the connection and its tool list without letting agents call anything.
  </Step>
</Steps>

## Personal accounts in the widget

Enable a personal server in Actions, then authenticate each customer through your backend. The widget asks the customer to connect only when a request needs access, and continues after authorization. Customers manage their own connections and saved approvals from **Connections** in the widget session list. Shared team connections are managed in Actions.

For personal servers, use **Capabilities** in the server's add or edit dialog to describe the actions it supports. This helps the agent request a connection for relevant tasks before it can see the customer's authorized tools. Include useful limits, keep the description aligned with enabled actions, and leave out credentials and customer data. This description is guidance, not a guarantee of access; tools are checked after the customer connects.

See [Widget connections](/widget/connections) for setup and [widget authentication](/widget/authentication#connect-each-customers-account) for account binding and optional restrictions.

## Per-Tool Control

Open a connected server's detail page to see its live tool catalog, grouped by what each tool does — write, fetch, or other. Switch individual tools off, or a whole group at once.

* The catalog is re-read from the server (`tools/list`) every time you open the page, so a tool the vendor adds later shows up already enabled.
* Switching a tool off stores it in a disabled set on your connection — it stays off even after the vendor's catalog changes, until you turn it back on.
* Write tools default to visible/open in the list since they're the ones worth auditing before an agent gets to call them; fetch tools default collapsed.

## How Agents Call MCP Tools

Once enabled, an MCP server's tools are available to the AI agent exactly like any other action — the agent decides whether a tool matches the customer's request, same as for [HTTP actions](/actions/introduction).

Tool names are namespaced as `<server>__<tool>` so two servers can each expose a tool with the same raw name (e.g. two different `search` tools) without colliding. If a server is unreachable when the agent tries to list its tools, that server's tools are omitted without breaking the whole tool list; its detail page reports the failure reason inline.

## Troubleshooting

| Symptom | Cause |
| - | - |
| "Reconnect required" badge | The OAuth grant expired or was revoked upstream. Reconnect from the server's detail page. |
| Server shows connected but tools list is empty or errors | The server itself is unreachable or erroring on `tools/list` — check the vendor's status, then revisit the page to re-probe. |
| A credential stopped working after you changed the server URL | Stored header values and OAuth tokens are pinned to the URL they were saved against. Repointing a server to a new host drops them — re-authenticate after changing the URL. |
| A tool you expected to see is missing | It may be switched off in [per-tool control](#per-tool-control) above, or the vendor removed it from their catalog. |

***

## Related Documentation

<CardGroup>
  <Card title="AI Actions" icon="bolt" href="/actions/introduction">
    How actions fit alongside integration and system tools.
  </Card>

  <Card title="Authentication" icon="shield-halved" href="/actions/authentication">
    Named secrets, global variables, and header auth for actions.
  </Card>

  <Card title="OpenAPI Import" icon="file-import" href="/actions/openapi-import">
    The other way to bulk-add actions, from your own OpenAPI spec.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/actions/troubleshooting">
    General action failures — import errors, 401s, AI not calling.
  </Card>
</CardGroup>


# OpenAPI Import
Source: https://docs.open.cx/actions/openapi-import

Generate OpenCX actions from an OpenAPI spec — upload from the dashboard or sync automatically from CI when the spec changes.

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

<Warning>
  **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.
</Warning>

## 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](/actions/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:

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

## Upload

<Tabs>
  <Tab title="From the dashboard">
    Go to **[Actions](https://platform.open.cx/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.
  </Tab>

  <Tab title="From CI">
    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](https://platform.open.cx/settings/access)**. See [API authentication](/api-reference/authentication).

    ### GitHub Actions

    ```yaml theme={"dark"}
    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 "file=@openapi.yaml"
    ```

    ### GitLab CI

    ```yaml theme={"dark"}
    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 "file=@openapi.yaml"
    ```

    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.
  </Tab>
</Tabs>

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

***

## Related Documentation

<CardGroup>
  <Card title="Build An Action" icon="plug" href="/actions/build-an-action">
    Hand-author a single action from the dashboard form.
  </Card>

  <Card title="Authentication" icon="shield-halved" href="/actions/authentication">
    Where secrets live for imported actions.
  </Card>

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

  <Card title="Troubleshooting" icon="wrench" href="/actions/troubleshooting">
    Import errors and post-import failures.
  </Card>
</CardGroup>


# Actions troubleshooting
Source: https://docs.open.cx/actions/troubleshooting

Fix common AI Actions failures — OpenAPI import errors, 401s that pass in Test, production calls that never land, and AI skipping an action.

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.

<Tip>
  Looking for setup? See [Build an action](/actions/build-an-action). For the runtime model, see [Execution](/actions/execution).
</Tip>

## 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](/actions/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](/actions/authentication) | 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](https://platform.open.cx/contacts). 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. |

<Info>
  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](/actions/execution) for the exact failure shapes.
</Info>

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

<CardGroup>
  <Card title="Build An Action" icon="plug" href="/actions/build-an-action">
    Re-check fields, magic values, and the Test button.
  </Card>

  <Card title="Execution" icon="diagram-project" href="/actions/execution">
    Re-check timeout, headers, and response handling.
  </Card>

  <Card title="Authentication" icon="shield-halved" href="/actions/authentication">
    Global variables, widget headers, context headers.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    What happens when repeated action failures escalate.
  </Card>
</CardGroup>


# AI Instructions
Source: https://docs.open.cx/ai-instructions/overview

Write the rules your AI follows and the answers it gives — a system prompt plus versioned training scenarios, all edited in one dashboard.

**AI Instructions** is the dashboard surface where you teach the AI directly — no connectors, no source systems. You write two things here: the **AI Profile** (how the agent behaves) and **training scenarios** (how it answers specific questions). Everything drafts first, publishes when you're ready.

<Tip>
  Open [**AI Instructions**](https://platform.open.cx/ai-instructions) in your OpenCX dashboard.
</Tip>

## What lives here

<AccordionGroup>
  <Accordion title="AI Profile — the agent's persona and ground rules" icon="id-badge">
    A single system prompt that defines who the agent is, the tone it uses, and the rules it never breaks. It's injected into every conversation before retrieval runs. Edit it as rich text; the editor keeps a **draft** alongside the published version so you can revise without affecting live conversations until you hit **Publish**.
  </Accordion>

  <Accordion title="Training scenarios — specific things to say or do" icon="list-check">
    Discrete instructions the AI applies on top of the profile. Each scenario has a type: **Behavioral** (always active — tone, formatting, policy reminders) or **Scenario-specific** (triggered when the customer's question matches). Scenarios carry their own draft/published lifecycle and version history. See [Training scenarios](/ai-instructions/training-scenarios).
  </Accordion>

  <Accordion title="Directories — folders for your scenarios" icon="folder-tree">
    Group scenarios by team, product area, or channel. Directories are flat org-wide — no nesting. Moving a scenario between directories is a drag; visibility settings (channels, segments) can be applied to a whole directory at once.
  </Accordion>

  <Accordion title="Version history per scenario" icon="clock-rotate-left">
    Every publish of a training scenario writes an immutable version. Open the history panel on any scenario to see who published what and when, and roll back — a rollback populates the draft with the old content so you can review before republishing. The AI Profile is a single mutable document and does not keep version history.
  </Accordion>
</AccordionGroup>

## When to use AI Instructions vs. the other pillars

Pick the surface closest to where your content already lives. Don't retype things you can sync.

| Pick this when… | Use |
| - | - |
| The rule is **universal** (tone, never reveal pricing, always confirm order ID) | **AI Instructions** — AI Profile or a Behavioral scenario |
| You have a **specific question** and a **specific answer** that's too important to rely on retrieval | **AI Instructions** — Scenario-specific |
| The content is a **customer-facing article** you'd want on a public Help Center anyway | [**Help Center**](/help-center/overview) |
| The content already lives in **Zendesk, Notion, Confluence, GitBook, Shopify, Intercom, Front, Freshdesk, or a website** | [**Knowledge Sources**](/knowledge/sources/overview) |

## Draft, publish, and what the AI sees

Every document in AI Instructions — the profile and every scenario — has a **published** state and a **draft** state.

* The draft is what you see while editing. It is **never** served to a customer.
* Publishing copies the draft over the live version. For scenarios, a new immutable version is written so you can roll back later.
* Discarding a draft wipes your unsaved changes and reverts to whatever is currently live.

Because everything is org-wide, a publish takes effect on the next conversation across every channel.

***

## Related Documentation

<CardGroup>
  <Card title="Training scenarios" icon="rabbit" href="/ai-instructions/training-scenarios">
    Behavioral vs. scenario-specific, channel and segment targeting, version history.
  </Card>

  <Card title="Help Center" icon="book-open" href="/help-center/overview">
    Author customer-facing articles that also train the AI.
  </Card>

  <Card title="Knowledge Sources" icon="brain" href="/knowledge/sources/overview">
    Sync content from Zendesk, Notion, Confluence, and more.
  </Card>

  <Card title="Agent Knowledge overview" icon="book" href="/knowledge/introduction">
    The three ways OpenCX learns what to say.
  </Card>
</CardGroup>


# Training scenarios
Source: https://docs.open.cx/ai-instructions/training-scenarios

Write behavioral rules and question-specific answers the AI honors, with draft, publish, versioning, and channel or segment targeting.

A **training scenario** is a single instruction you write for the AI. Every scenario is either **behavioral** (the AI applies it on every message) or **scenario-specific** (the AI applies it when the customer asks a matching question). Scenarios are the fastest way to teach the AI something without connecting a source or writing an article.

<Tip>
  Add a scenario from [**AI Instructions**](https://platform.open.cx/ai-instructions) — click the **+** next to a directory in the sidebar.
</Tip>

## Behavioral vs. scenario-specific

Pick the type that matches the job. You can change a scenario's type later, but the draft/published state resets when you do.

| | Behavioral | Scenario-specific |
| - | - | - |
| **When it applies** | Every conversation, on every message | When the customer's question matches the scenario's trigger question |
| **How it's matched** | Always on — injected before retrieval | Semantic search against the trigger question; top matches are injected |
| **Good fit for** | Tone, formatting rules, policy reminders, things that must hold on every reply | "When customer asks X, say Y" — refund policy, business hours, known product limitation |
| **Example trigger** | *(none)* | "How do I cancel my subscription?" |
| **Example content** | "Always confirm the order ID before discussing shipping. Never share another customer's details." | "Cancel from Account → Billing. Your access continues through the end of the current billing period." |

<Note>
  Scenario-specific instructions match on **meaning**, not exact text. "Can I cancel?" and "How do I end my subscription?" hit the same scenario as long as the trigger question covers the intent.
</Note>

## Write a scenario

<Steps>
  <Step title="Open AI Instructions">
    Go to [**AI Instructions**](https://platform.open.cx/ai-instructions). Pick the directory where the scenario should live — or click **New directory** first if you want to organize it separately.
  </Step>

  <Step title="Add a new scenario">
    Click **+ New scenario** in the sidebar. Give it a clear title (this is only shown inside the dashboard — the AI doesn't see it).
  </Step>

  <Step title="Pick the type and write the content">
    Set the type to **Behavioral** or **Scenario-specific**. For scenario-specific, fill the trigger question with the way a customer would actually phrase it. Write the answer or rule in the content editor — plain language is fine; the AI will rephrase it in its own voice unless you tell it not to.
  </Step>

  <Step title="Optional — restrict to channels or segments">
    Under **Visibility**, pick channels (Chat, Email, SMS, WhatsApp, Phone, etc.) and contact segments the scenario should apply to. Leave both empty to apply everywhere. Phone agents also need the scenario, or its folder, selected in their [knowledge sources](/phone/agent-config#knowledge-sources).
  </Step>

  <Step title="Publish">
    Click **Publish**. The scenario takes effect on the next message across every channel you selected. Your draft is preserved — if you keep editing, you'll see a pending draft badge until you publish again.
  </Step>
</Steps>

## Format instruction content

Select text to open the formatting toolbar: text styles, bold and italics, links, **More formatting** for colors, highlights and alignment, and **Insert** for tables, checklists, quotes, code blocks and dividers. Type `/` to insert the same blocks without selecting text first. Inside a table, the handles above a column or beside a row add, remove and merge cells; drag a column boundary to resize it. Click a link to edit it; **⌘-click** (**Ctrl-click** on Windows and Linux) opens it in a new tab. The same tools are available when editing the AI profile.

## Common patterns

Three canonical scenario-specific examples you can adapt. Each is written as the trigger question + the answer you want the AI to give.

```
Trigger: Can I get a refund? / Cancel my order / Money back
Answer:  We don't issue refunds directly, but I can help resolve the issue.
         Could you tell me what's not working so I can look into it?
```

```
Trigger: What are your hours? / When are you open? / Business hours
Answer:  Support is available Monday–Friday, 9am–5pm EST. Outside those
         hours, leave a message and we'll reply on the next business day.
```

```
Trigger: How much does it cost? / Pricing / Subscription fee
Answer:  Plans start at $49/month for Basic. Full pricing breakdown is at
         example.com/pricing — want me to walk through which plan fits your use case?
```

Keep answers in the voice you want the customer to hear — the AI will follow your phrasing closely on scenario-specific matches.

## Channel and segment targeting

Leave the targeting fields empty unless you need the scope. When you set them:

* **Channels** — comma-separated list. Valid values: Chat Widget, Email, SMS, WhatsApp, Phone, Slack, Instagram, Messenger, API. A scenario with channels set only fires on those channels.
* **Segments** — OpenCX contact segments. A scenario restricted to segments only fires if the contact is a member of at least one listed segment. Anonymous conversations (no contact) never match segment-restricted scenarios.

Setting **both** requires **both** to match. Use directory-level visibility to apply the same rule to a whole folder at once.

## Version history

Every publish writes an immutable version you can review or roll back to.

* **See versions** — open a scenario and click **History**. Each row shows the version number, who published it, and when.
* **Roll back** — pick a version and click **Restore**. The content loads into your draft; nothing changes for customers until you publish.
* **Drafts are not versioned.** Only published versions are kept. Save aggressively and publish when you're ready.

## Good to know

<AccordionGroup>
  <Accordion title="Drafts are never shown to customers" icon="eye-slash">
    Only the published version of a scenario is served at answer time. Drafts, including new unpublished scenarios, are invisible to the AI until you publish them.
  </Accordion>

  <Accordion title="Move scenarios between directories" icon="folder-tree">
    Drag a scenario in the sidebar to move it. Visibility settings on a directory (channels, segments) can be applied to every scenario inside with one action.
  </Accordion>

  <Accordion title="Scenarios don't replace knowledge sources" icon="brain">
    A directory of 500 refund scenarios is harder to maintain than one Help Center article or a synced Zendesk category. Use scenarios for the things that would be lost in a long article — edge cases, policy carve-outs, overrides.
  </Accordion>

  <Accordion title="Session learnings create scenario drafts" icon="wand-magic-sparkles">
    When you mark an agent reply as "teach the AI" from a resolved session, OpenCX drafts a scenario-specific instruction pre-filled from the conversation. It lands as a draft — review and publish it the same way you would any other scenario.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Instructions overview" icon="sliders" href="/ai-instructions/overview">
    AI Profile, directories, and how direct training fits alongside the rest.
  </Card>

  <Card title="Autopilot topics" icon="compass" href="/handoff/topics">
    Topic gating for when the AI should hand off instead of answer.
  </Card>

  <Card title="Help Center articles" icon="file-lines" href="/help-center/articles">
    Long-form content the AI cites in customer replies.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    Sync existing docs instead of rewriting them as scenarios.
  </Card>
</CardGroup>


# Create an action
Source: https://docs.open.cx/api-reference/actions/create

post /actions
Create actions your AI agent can call during sessions. Configure endpoints, dynamic inputs, and fixed parameter values through the API.

Set `payload.parameters[].value` to a non-empty string to supply a fixed query or path parameter on every call. Omit `value` or set it to `null` when the parameter should be filled at call time. A `schema.example` only illustrates an input; it does not supply a fixed value.

For example, an account identifier can stay fixed while the order reference varies:

```json theme={"dark"}
{
  "parameters": [
    {
      "name": "accountId",
      "in": "query",
      "required": true,
      "value": "account-123",
      "schema": { "type": "string" }
    },
    {
      "name": "orderId",
      "in": "path",
      "required": true,
      "value": null,
      "schema": { "type": "string" }
    }
  ]
}
```

Place these parameters inside `payload` alongside the action's path and method. See [Build an action](/actions/build-an-action) for dashboard setup.


# Delete an action
Source: https://docs.open.cx/api-reference/actions/delete

delete /actions/{action_id}
Permanently delete a single action by ID. Use when programmatically managing the AI actions (tools) your agents can call, typically as part of a deploy or environment sync.



# Delete all actions
Source: https://docs.open.cx/api-reference/actions/delete-all-actions

delete /actions
Delete all actions. Use when programmatically managing the AI actions (tools) your agents can call, typically as part of a deploy or environment sync.



# Delete all actions
Source: https://docs.open.cx/api-reference/actions/delete_all

delete /actions/all
Delete all actions. Use when programmatically managing the AI actions (tools) your agents can call, typically as part of a deploy or environment sync.



# Get an action
Source: https://docs.open.cx/api-reference/actions/get

get /actions/{action_id}
Get a single action by ID. Use when programmatically managing the AI actions (tools) your agents can call, typically as part of a deploy or environment sync.



# Import actions from OpenAPI spec
Source: https://docs.open.cx/api-reference/actions/import

put /actions/import
Import actions from OpenAPI spec — Upload an OpenAPI specification file (v2, v3, or v3.



# Import from openapi file
Source: https://docs.open.cx/api-reference/actions/import-from-openapi-file

put /actions
Import AI actions in bulk by uploading an OpenAPI spec. Use when syncing a large set of tools from an external API catalogue or a deploy pipeline.



# AI Actions
Source: https://docs.open.cx/api-reference/actions/index

The AI Actions API lets you manage the HTTP API calls your AI agent can make during conversations.

The AI Actions API lets you manage the HTTP API calls your AI agent can make during conversations. Actions connect your AI to external systems — looking up orders, processing refunds, booking appointments, and more.

## How Actions Work

Each action defines an HTTP API call the AI can make:

* **Endpoint** — The URL to call
* **Method** — GET, POST, PUT, PATCH, or DELETE
* **Payload** — OpenAPI-style specification defining parameters, request body, and response format
* **Channels** — Which communication channels (web, email, WhatsApp, etc.) can trigger this action

The AI decides when to call an action based on the conversation context and the action's name/description.

## Available Endpoints

<CardGroup>
  <Card title="List Actions" icon="list" href="./list">
    List all configured actions
  </Card>

  <Card title="Get Action" icon="magnifying-glass" href="./get">
    Get a single action by ID
  </Card>

  <Card title="Create Action" icon="plus" href="./create">
    Create a new action
  </Card>

  <Card title="Update Action" icon="pen" href="./update">
    Update an existing action
  </Card>

  <Card title="Delete Action" icon="trash" href="./delete">
    Delete a single action
  </Card>

  <Card title="Delete All" icon="trash-can" href="./delete_all">
    Delete all actions
  </Card>

  <Card title="Import from OpenAPI" icon="file-import" href="./import">
    Import actions from an OpenAPI spec file
  </Card>

  <Card title="List Tags" icon="tags" href="./list_tags">
    List all unique action tags
  </Card>
</CardGroup>


# List all actions
Source: https://docs.open.cx/api-reference/actions/list

get /actions
List all actions configured for your organization. Use when programmatically managing the AI actions (tools) your agents can call, typically as part of a deploy or environment…



# List distinct action tags
Source: https://docs.open.cx/api-reference/actions/list_tags

get /actions/tags
List distinct action tags — Get all unique tags used across actions in your organization.



# Update an action
Source: https://docs.open.cx/api-reference/actions/update

patch /actions/{action_id}
Update an existing action. Use when programmatically managing the AI actions (tools) your agents can call, typically as part of a deploy or environment sync.

When you supply `payload`, it replaces the action's existing payload. Keep the full operation specification, including any fixed `parameters[].value` fields. To change only the action's name or description, omit `payload`.

Fixed query and path parameters use a non-empty string in `value`. Omit that field or set it to `null` for a dynamic input. A `schema.example` does not replace a fixed value. See [Create an action](/api-reference/actions/create) for an example.


# Audit Logs API
Source: https://docs.open.cx/api-reference/audit-logs/index

Read your workspace audit trail over the API: sign-ins, sign-outs and every change, with filters and stable cursor paging. Use it to export or monitor activity.

The Audit Logs API returns your workspace's audit trail, newest first. It covers teammate sign-ins and sign-outs, and every change made in the dashboard, over the API, or by automations. See [Audit logs overview](/security/audit-logs) for what the log records.

## Key Concepts

* **Scope required** — `audit-logs:read`
* **Event** — `event_type` says what happened (`login`, `logout`, `create`, `update`, `api_key_create`, …). `entity_type` and `entity_id` say what it happened to
* **Actor** — `actor_type` is `user`, `system` or `api`. For an API key, `api_key` names the key and who created it
* **Changes** — `changes.before` and `changes.after` hold the fields that changed, when the event has them
* **Read-only** — entries can't be edited or deleted

## Sign-ins and sign-outs

A sign-in is an event with `entity_type: "user"` and `event_type: "login"`. `metadata.method` says how the teammate signed in: `google`, `microsoft`, `sso`, `partner`, `password` or `other`. For `sso`, `metadata.sso_provider_id` names the connection.

A sign-out has `event_type: "logout"`. `metadata.reason` says why it ended:

| `reason` | Meaning |
| - | - |
| `signed_out` | The teammate signed out. `actor_type` is `user` |
| `expired` | The sign-in expired. Recorded the next time that browser loaded the dashboard |
| `revoked` | The sign-in was ended before it expired, including by the teammate's removal from another workspace |
| `removed_from_org` | An admin of this workspace removed the teammate. `metadata.revoked_sessions` counts the sign-ins ended |
| `deprovisioned` | This workspace's identity provider deprovisioned the teammate |
| `deactivated` | The identity provider deactivated the teammate |

`metadata.user_email` always names the teammate, including when the system ended the sign-in. `ip_address` and `user_agent` are the request that signed in or out, when there was one.

## Filtering

Every filter is optional, and filters combine. `eventType`, `entityType` and `eventCategory` accept one value, or the same parameter repeated to match any of several:

```bash theme={"dark"}
curl "https://api.open.cx/audit-logs?eventType=login&eventType=logout&startDate=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Use `entityId` to follow one thing, for example a workflow with `entityType=workflow&entityId=<workflow id>`. Use `userId` to follow one teammate: everything they did, plus the sign-outs the system ended for them.

## Paging

Responses carry `pagination` (`total`, `page`, `limit`, `totalPages`) and `next_cursor`.

* **Cursor paging (recommended)** — pass `next_cursor` back as `cursor` until it is `null`. Events written while you page never shift the pages, so nothing is skipped or read twice. When `cursor` is set, `page` is ignored
* **Page numbers** — `page` and `limit` keep working. Pages can shift if new events arrive between requests

`limit` is 20 by default and at most 100. `page` must be at least 1, and `cursor` must come from this workspace. Anything else is a `400`.


# List audit logs
Source: https://docs.open.cx/api-reference/audit-logs/list

get /audit-logs
List audit log events newest first, filtered by event, entity, actor or date, and paged by cursor or page number. Requires the audit-logs:read scope.



# Authentication
Source: https://docs.open.cx/api-reference/authentication

Authenticate every API request with a Bearer token. Generate keys per scope, rotate them freely, and handle the standard 401/403 error responses.

All API requests require a **Bearer token** in the `Authorization` header.

```bash theme={"dark"}
curl https://api.open.cx/contacts \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Generate an API key

1. Go to [Settings → Access](https://platform.open.cx/settings/access) in the OpenCX dashboard.
2. Click **Create API Key**.
3. Give it a name (e.g. "Production", "Staging").
4. Choose access level:
   * **Full access** — the key can call every endpoint with no restrictions.
   * **Custom scopes** — select only the resources and actions (read / write) this key needs.
5. Copy the key.

<Note>
  Existing keys created before scopes were introduced remain full-access.
</Note>

<Warning>
  The full key is only shown once. Store it securely — if you lose it, generate
  a new one.
</Warning>

***

## Using the key

Pass the key as a Bearer token in the `Authorization` header on every request:

```bash theme={"dark"}
Authorization: Bearer ocx_live_abc123...
```

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X GET https://api.open.cx/contacts \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={"dark"}
  const response = await fetch("https://api.open.cx/contacts", {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  });
  ```

  ```python Python theme={"dark"}
  import requests

  response = requests.get(
      'https://api.open.cx/contacts',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
  )
  ```
</CodeGroup>

***

## Scopes

Scopes restrict an API key to specific resources and actions. A **full-access** key bypasses all scope checks, while a **scoped** key can only call the endpoints it was granted.

Each scope follows the pattern `resource:action`, where action is `read` (GET / list) or `write` (create / update / delete).

### Available scopes

| Resource | Read | Write |
| - | - | - |
| Actions | `actions:read` | `actions:write` |
| Agent availability | `agent-availability:read` | `agent-availability:write` |
| Audit logs | `audit-logs:read` | — |
| Autopilot | `autopilot:read` | `autopilot:write` |
| Blocklist | `blocklist:read` | `blocklist:write` |
| Chat sessions | `chat-sessions:read` | `chat-sessions:write` |
| Contact segments | `segments:read` | `segments:write` |
| Contacts | `contacts:read` | `contacts:write` |
| Crawl | `crawl:read` | `crawl:write` |
| CSAT | `csat:read` | `csat:write` |
| Email | `email:read` | `email:write` |
| Handoff analytics | `handoff-analytics:read` | — |
| Help center | `help-center:read` | `help-center:write` |
| Impact report | `impact-report:read` | — |
| Inbox views | `inbox-views:read` | `inbox-views:write` |
| Insights | `insights:read` | `insights:write` |
| Media | — | `media:write` |
| Office hours | `office-hours:read` | `office-hours:write` |
| Organization | `org:read` | `org:write` |
| Phone | `phone:read` | `phone:write` |
| Redaction | `redaction:read` | `redaction:write` |
| Salesforce CRM | `salesforce-crm:read` | — |
| Salesforce MIAW | — | `salesforce-miaw:write` |
| Secrets | — | `secrets:write` |
| Sequences | `sequences:read` | `sequences:write` |
| SIP | `sip:read` | `sip:write` |
| Slack | `slack:read` | `slack:write` |
| SLA analytics | `sla-analytics:read` | — |
| SLA policies | `sla:read` | `sla:write` |
| Tags | `tags:read` | `tags:write` |
| Teams | `teams:read` | `teams:write` |
| Training | `training:read` | `training:write` |
| Users | `users:read` | `users:write` |
| WhatsApp | `whatsapp:read` | `whatsapp:write` |
| Widget | `widget:read` | `widget:write` |
| Workflows | `workflows:read` | `workflows:write` |

<Note>
  Read-only resources (Audit logs, Handoff analytics, Impact report, Salesforce
  CRM, SLA analytics) have no write scope. Media and Secrets are write-only —
  there is no `media:read` or `secrets:read`. Secret values are never returned
  by any endpoint, so no scope can read one back. Salesforce MIAW only exposes a
  write scope for sending webhook events.
</Note>

<Note>
  Agent availability covers reading and setting a teammate's availability,
  availability status, and chat capacity, without inviting or managing
  members. `users:read` and `users:write` also grant it.
</Note>

<Note>
  Workflows also expose `workflows:trigger`, granted independently of read /
  write. It only authorizes calls to a workflow webhook trigger URL whose
  trigger configuration has **Access Control** set to *Private (Authentication
  Required)*. Public webhook triggers do not require any scope.
</Note>

***

## Error responses

| Status | Meaning |
| - | - |
| `401 Unauthorized` | Missing or invalid API key |
| `403 Forbidden` | Key is valid but lacks the required scope |

**401 — invalid or missing key**

```json theme={"dark"}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}
```

**403 — missing scope**

```json theme={"dark"}
{
  "statusCode": 403,
  "message": "This API key does not have the required scope: \"tags:read\"."
}
```

***

## Best practices

* **Never commit keys to source control.** Use environment variables or a secrets manager.
* **Rotate keys periodically.** You can create multiple keys and revoke old ones from the dashboard.
* **Use separate keys for each environment** (production, staging, development) so revoking one doesn't break the others.
* **Use scoped keys in production.** Grant only the permissions each integration needs (principle of least privilege).
* **Prefer separate keys per integration** so revoking one doesn't break others, and each gets only the scopes it needs.


# Get autopilot status
Source: https://docs.open.cx/api-reference/autopilot/get

get /autopilot
Get the autopilot enabled/disabled status for each channel. Use when toggling or configuring autopilot mode across agents.



# Enable or disable autopilot for a channel
Source: https://docs.open.cx/api-reference/autopilot/update

put /autopilot
Enable or disable autopilot for a channel — Turn autopilot on or off for a specific channel.



# Block a contact
Source: https://docs.open.cx/api-reference/blocklist/block_contact

post /blocklist/contacts
Block a contact by email. Use when stopping a visitor from reaching the AI assistant, such as abuse, spam or internal test accounts.



# Block email domains
Source: https://docs.open.cx/api-reference/blocklist/block_domains

post /blocklist/domains
Block one or more email domains. Use when stopping a visitor from reaching the AI assistant, such as abuse, spam or internal test accounts.



# Block IP addresses
Source: https://docs.open.cx/api-reference/blocklist/block_ips

post /blocklist/ips
Block IP addresses or CIDR ranges, IPv4 or IPv6, optionally with expires_in_hours. Applies to web widget traffic — email and WhatsApp carry no visitor IP.



# Check if a contact is blocked
Source: https://docs.open.cx/api-reference/blocklist/check_contact

get /blocklist/contacts/check/{contact_id}
Check whether a specific contact is currently blocked. Use when stopping a visitor from reaching the AI assistant, such as abuse, spam or internal test accounts.



# Check if a domain or email is blocked
Source: https://docs.open.cx/api-reference/blocklist/check_domain

get /blocklist/domains/check
Check if a domain or email is blocked. Use when stopping a visitor from reaching the AI assistant, such as abuse, spam or internal test accounts.



# Check if an IP is blocked
Source: https://docs.open.cx/api-reference/blocklist/check_ip

get /blocklist/ips/check
Check whether an IP address is blocked. Matches exact entries as well as any CIDR range that contains the address.



# Blocklist
Source: https://docs.open.cx/api-reference/blocklist/index

Manage blocked contacts, email domains, and IP addresses. Use when stopping abusive or unwanted visitors from reaching your AI assistant.

The Blocklist API lets you manage blocked contacts, blocked email domains, and blocked IP addresses. Blocked visitors are ignored by the AI — instead of an automated response they receive a short message explaining they cannot contact the company right now. You can customise that message per organization in **Settings → Autopilot**.

## Blocked Contacts

Block individual contacts by email. Useful for stopping the AI from responding to abusive users, spam accounts, or internal test contacts.

## Blocked Domains

Block entire email domains (e.g. "spam.com"). All contacts with emails on blocked domains will be ignored by the AI. Supports blocking multiple domains at once.

## Blocked IPs

Block a single address (e.g. "203.0.113.7") or a whole CIDR range (e.g. "203.0.113.0/24"), IPv4 or IPv6. Useful against widget abuse where the visitor keeps creating throwaway contacts, so contact- and domain-blocking never bite.

The address is resolved from Cloudflare's `CF-Connecting-IP` header, which cannot be forged by the client. A client IP is only observable on the web/widget channels; once a session has been seen from a blocked address the block continues to apply to that session on every channel.

## Available Endpoints

<CardGroup>
  <Card title="List Blocked Contacts" icon="list" href="/api-reference/blocklist/list_contacts">
    List all blocked contacts
  </Card>

  <Card title="Block Contact" icon="user-slash" href="/api-reference/blocklist/block_contact">
    Block a contact by email
  </Card>

  <Card title="Check Contact" icon="magnifying-glass" href="/api-reference/blocklist/check_contact">
    Check if a contact is blocked
  </Card>

  <Card title="Unblock Contact" icon="user-check" href="/api-reference/blocklist/unblock_contact">
    Remove a contact from the blocklist
  </Card>

  <Card title="List Blocked Domains" icon="list" href="/api-reference/blocklist/list_domains">
    List all blocked domains
  </Card>

  <Card title="Block Domains" icon="globe" href="/api-reference/blocklist/block_domains">
    Block one or more email domains
  </Card>

  <Card title="Check Domain" icon="magnifying-glass" href="/api-reference/blocklist/check_domain">
    Check if a domain or email is blocked
  </Card>

  <Card title="Unblock Domain" icon="globe" href="/api-reference/blocklist/unblock_domain">
    Remove a domain from the blocklist
  </Card>

  <Card title="List Blocked IPs" icon="list" href="/api-reference/blocklist/list_ips">
    List all blocked IPs and CIDR ranges
  </Card>

  <Card title="Block IPs" icon="network-wired" href="/api-reference/blocklist/block_ips">
    Block one or more IP addresses or ranges
  </Card>

  <Card title="Check IP" icon="magnifying-glass" href="/api-reference/blocklist/check_ip">
    Check if an IP is blocked
  </Card>

  <Card title="Unblock IP" icon="network-wired" href="/api-reference/blocklist/unblock_ip">
    Remove an IP from the blocklist
  </Card>
</CardGroup>


# List blocked contacts
Source: https://docs.open.cx/api-reference/blocklist/list_contacts

get /blocklist/contacts
List all blocked contacts. Use when stopping a visitor from reaching the AI assistant, such as abuse, spam or internal test accounts.



# List blocked domains
Source: https://docs.open.cx/api-reference/blocklist/list_domains

get /blocklist/domains
List all blocked email domains. Use when stopping a visitor from reaching the AI assistant, such as abuse, spam or internal test accounts.



# List blocked IPs
Source: https://docs.open.cx/api-reference/blocklist/list_ips

get /blocklist/ips
List all blocked IP addresses and CIDR ranges. Use when auditing which visitors are barred from the AI assistant, or reconciling against an external abuse list.



# List IP addresses seen in recent sessions
Source: https://docs.open.cx/api-reference/blocklist/session_ip_activity

get /blocklist/ips/session-activity
List the IP addresses opening sessions, ranked by volume, with distinct contacts per address. Use when deciding which addresses to block instead of guessing.



# Unblock a contact
Source: https://docs.open.cx/api-reference/blocklist/unblock_contact

delete /blocklist/contacts/{id}
Unblock a contact — Remove a contact from the blocklist. Use when stopping a visitor from reaching the AI assistant, such as abuse, spam or internal test accounts.



# Unblock a domain
Source: https://docs.open.cx/api-reference/blocklist/unblock_domain

delete /blocklist/domains/{id}
Unblock a domain — Remove a domain from the blocklist. Use when stopping a visitor from reaching the AI assistant, such as abuse, spam or internal test accounts.



# Unblock an IP
Source: https://docs.open.cx/api-reference/blocklist/unblock_ip

delete /blocklist/ips/{id}
Remove an IP address or CIDR range from the blocklist, restoring the visitor’s access to the AI assistant.



# List WAV recordings for call flows
Source: https://docs.open.cx/api-reference/call-flows/list-assets

get /call-flows/assets
List uploaded WAV recordings in your organization, including the IDs used by native IVR workflow nodes.

Requires `workflows:read`, with telephony and Classical IVR enabled. Returns the organization’s recordings, newest first, including their IDs, names, sample rates, channel counts, durations in seconds and creation times. This endpoint returns the full list without pagination parameters.

Use a recording ID in a [Classical IVR workflow](/phone/call-flows).


# Assign an active call flow to a phone number
Source: https://docs.open.cx/api-reference/call-flows/set-binding

put /call-flows/binding
Assign an active IVR Incoming Call workflow to an organization phone number, or remove its call-flow assignment.

A phone number can have only one inbound destination: an IVR or a phone agent. Assigning an IVR to a number already assigned to an agent returns a validation error; unassign the number from the agent first. Assigning a phone agent to an IVR number is also rejected until the IVR assignment is removed.

Use `workflowId: null` to remove the IVR assignment. Assigning a different active IVR replaces the previous IVR for that number. Changes apply to new calls.

Requires both `phone:write` and `workflows:write` scopes. Telephony and Classical IVR must be enabled. The workflow must be active, use the `ivr-incoming-call` trigger and belong to the same organization as the number.

See [Classical IVR setup](/phone/call-flows) for activation and real-call testing.


# Upload an immutable WAV recording
Source: https://docs.open.cx/api-reference/call-flows/upload-asset

post /call-flows/assets
Upload an immutable WAV recording for a native call flow using base64 audio and workflow write permission.

Requires `workflows:write`, with telephony and Classical IVR enabled. Send the WAV bytes as base64 in `wavBase64` and a recording name in `name`.

Supports mono or stereo, 16-bit PCM, A-law or mu-law WAV files at 8, 16, 24, 32, 44.1 or 48 kHz. The decoded file must be at most 20 MB and five minutes long. Invalid or unsupported audio is rejected.

The response contains the recording ID, name, sample rate, channels, duration in seconds and creation time. Use the ID in a Classical IVR node. Every upload creates a new recording; it does not replace an existing recording, activate a workflow or change number routing. See [WAV recordings](/phone/call-flows#wav-recordings).


# Add a tag to a chat session
Source: https://docs.open.cx/api-reference/chat-sessions/add_tag

post /chat/sessions/{session_id}/tags
Add a tag to a session. The tag is created if it does not exist yet, and synced to the underlying ticketing system when one is connected.



# Assign or unassign a chat session
Source: https://docs.open.cx/api-reference/chat-sessions/assignee

post /chat/sessions/{session_id}/assignee
Assign a session to a teammate, named either by user ID or by email. Send either field as null to unassign. Use `GET /users` to look up user IDs.



# Create a chat session
Source: https://docs.open.cx/api-reference/chat-sessions/create

post /chat/sessions
Create a chat session — Creates a new chat session for the organization. Use when orchestrating conversations from code — creating sessions, sending messages, or listing history…

## Custom data

Pass top-level `custom_data` to store session-level attributes on the new chat session, such as an order ID, cart value, or routing flag. Values can be strings, numbers, or booleans, and are returned by [Get Session](/api-reference/chat-sessions/get).

```json theme={"dark"}
{
  "channel": { "type": "api" },
  "custom_data": { "order_id": "ord_123", "cart_value": 149.99, "priority": "high" }
}
```

Nested objects are rejected with a `400`. To attach contact-level attributes instead, use `contact.custom_data` on [Send Message](/api-reference/chat-sessions/send).

<Note>
  Session `custom_data` set through this endpoint is stored on the session but is **not** synced to a connected external ticketing system (e.g. Intercom or HubSpot).
</Note>


# Create a session comment
Source: https://docs.open.cx/api-reference/chat-sessions/create_comment

post /chat/sessions/{session_id}/comments
Add an internal note (agent comment) to a session via the REST API. Notes are visible to agents in the inbox and never shown to the customer.

## Internal notes

Session comments are internal notes: agents see them in the inbox, the customer never does.

A comment can be anchored two ways:

* **Attached to a message** — pass `thread_id`, the UUID of the message being commented on. Message UUIDs come from [Session History](/api-reference/chat-sessions/list_history), where each event's `id` is its message UUID.
* **Session-level** — omit `thread_id`. The note stands on its own in the session timeline, not attached to any message.

`agent_id` is the numeric ID of the team member authoring the note.

## Retrieving comments

Comments are part of the session timeline, so there is no separate list endpoint. Use [Session History](/api-reference/chat-sessions/list_history) and filter for events where `event.type` is `human_agent_comment`. Each one carries the author (`human_agent_id`), the text (`content.text`), and the thread it belongs to (`comment_thread_id`).

## Deep linking

You can link agents straight to a message or note in the dashboard inbox:

* **To a message:** `https://platform.open.cx/inbox/?s=<session_id>&h=<message_uuid>`
* **To a comment on a message:** `https://platform.open.cx/inbox/?s=<session_id>&thread=<thread_id>&comment=<comment_uuid>` — `thread_id` is the message the comment is attached to, and `comment_uuid` is the `uuid` returned when the comment is created.
* **To a session-level comment:** `https://platform.open.cx/inbox/?s=<session_id>&comment=<comment_uuid>&h=<comment_uuid>` — the note is its own timeline row, so `h` targets the note itself.

The inbox opens the session and scrolls to the target.


# Delete a session comment
Source: https://docs.open.cx/api-reference/chat-sessions/delete_comment

delete /chat/sessions/{session_id}/comments/{comment_uuid}
Delete a session comment — Removes an internal note from a chat session. Only the agent who authored the note may delete it.

Deletes an internal note. The note stops appearing in the inbox and in [List history](/api-reference/chat-sessions/list_history), and the endpoint answers `204` with no body.

The acting agent is passed as the `agent_id` **query parameter**, since a `DELETE` carries no body:

```bash theme={"dark"}
curl -X DELETE "https://api.open.cx/chat/sessions/{session_id}/comments/{comment_uuid}?agent_id=42" \
  -H "Authorization: Bearer $OPENCX_API_KEY"
```

Only the note's author may delete it — anyone else receives a `403`. A `comment_uuid` that belongs to a different session returns a `404`.


# Filter chat sessions
Source: https://docs.open.cx/api-reference/chat-sessions/filter

post /chat/sessions/filter
Search and filter chat sessions with advanced criteria. Use when orchestrating conversations from code — creating sessions, sending messages, or listing history for an external…

Each returned session includes all of its assigned `tags`, even when filtering by
a subset of tag names. Each tag contains `tag_name` and `created_at`. Tags are
ordered by name; sessions without tags return an empty array.

The `support_team` field contains the assigned support team's `id` and `name`.
The ID remains stable when the team is renamed. This field is `null` when no
support team can be resolved for the session.

The `first_human_message_at` field contains the first recorded human reply time as an
ISO 8601 timestamp, or `null` when no human reply has been recorded. Internal notes
and automated messages do not set this timestamp. Later human replies do not change it.

The `title` field is the session title: the email subject, a subject set by an agent,
or an AI-generated title. It is `null` until one is set.

Use `assignee` to identify who is currently assigned to a session:

| Type | Example | Meaning |
| - | - | - |
| Human | `{"type":"human","id":77,"name":"Alex Smith"}` | The numeric ID matches `GET /users`. |
| AI | `{"type":"ai"}` | AI is assigned; no ID or name is returned. |
| None | `{"type":"none"}` | The session is unassigned. |

A human assignee's `name` matches the organization display name in `GET /users`.
An organization name override takes precedence; a blank or missing override falls
back to the account name. The name is `null` if the user is no
longer a member of the organization or cannot be found; the recorded ID remains
available for historical attribution. Reading a session does not require the
`users:read` scope. Reading the user directory, including emails, does.

The response field `assignee_id` is deprecated. Human IDs remain strings there;
AI and unassigned sessions return `null`. Clients that previously used the AI
placeholder must switch to `assignee.type`. Assignment requests continue to use
`assignee_id` with a numeric human user ID or `null` to unassign.


# Get a chat session
Source: https://docs.open.cx/api-reference/chat-sessions/get

get /chat/sessions/{session_id}
Get a chat session — Retrieves details and call recording of a specific chat session by its ID. Use when orchestrating conversations from code — creating sessions, sending messages, or listing…

The response includes `tags`, with each tag's `tag_name` and `created_at` timestamp.
Tags are ordered by name. Sessions without tags return an empty array.

The `support_team` field contains the assigned support team's `id` and `name`.
The ID remains stable when the team is renamed. This field is `null` when no
support team can be resolved for the session.

The `first_human_message_at` field contains the first recorded human reply time as an
ISO 8601 timestamp, or `null` when no human reply has been recorded. Internal notes
and automated messages do not set this timestamp. Later human replies do not change it.

The `title` field is the session title: the email subject, a subject set by an agent,
or an AI-generated title. It is `null` until one is set.

The `recording_url` field contains a download link for the latest completed phone
or web call recording, or `null` when unavailable. Links expire after seven days;
request the session again to get a fresh link. This field is only included when
getting a session by ID.

Use `assignee` to identify who is currently assigned to a session:

| Type | Example | Meaning |
| - | - | - |
| Human | `{"type":"human","id":77,"name":"Alex Smith"}` | The numeric ID matches `GET /users`. |
| AI | `{"type":"ai"}` | AI is assigned; no ID or name is returned. |
| None | `{"type":"none"}` | The session is unassigned. |

A human assignee's `name` matches the organization display name in `GET /users`.
An organization name override takes precedence; a blank or missing override falls
back to the account name. The name is `null` if the user is no
longer a member of the organization or cannot be found; the recorded ID remains
available for historical attribution. Reading a session does not require the
`users:read` scope. Reading the user directory, including emails, does.

The response field `assignee_id` is deprecated. Human IDs remain strings there;
AI and unassigned sessions return `null`. Clients that previously used the AI
placeholder must switch to `assignee.type`. Assignment requests continue to use
`assignee_id` with a numeric human user ID or `null` to unassign.


# Hand the session off to a human agent
Source: https://docs.open.cx/api-reference/chat-sessions/handoff

post /chat/sessions/{session_id}/handoff
Hand off a chat session — Hands the session off to a human agent, re-running the pipeline even if already handed off. Use to escalate a conversation from code.



# Sessions
Source: https://docs.open.cx/api-reference/chat-sessions/index

A session in Open represents any interaction between a customer and your support team.

A session in Open represents any interaction between a customer and your support team. This could be a conversation with an AI agent, a human agent, or both working together to help the customer.

## What is a Session?

Think of a session as a complete conversation thread. It starts when a customer reaches out and ends when their inquiry is resolved. Each session can include:

* Messages between the customer and AI
* Messages between the customer and human agents
* Files and attachments
* System actions and responses
* Session metadata (duration, channel, status)

## Communication Channels

Sessions can happen through multiple channels:

<CardGroup>
  <Card title="Web Chat" icon="globe">
    Real-time chat through your website or app
  </Card>

  <Card title="Email" icon="envelope">
    Email conversations with threaded replies
  </Card>

  <Card title="SMS" icon="message">
    Text message conversations
  </Card>

  <Card title="Phone" icon="phone">
    Voice calls with transcription
  </Card>

  <Card title="WhatsApp" icon="whatsapp">
    WhatsApp Business conversations
  </Card>

  <Card title="Slack" icon="slack">
    Slack conversations
  </Card>

  <Card title="API" icon="code">
    API integrations
  </Card>
</CardGroup>

## How Sessions Work

1. **Session Start**

   * Customer initiates contact through any channel
   * System creates a new session
   * AI agent begins the conversation

2. **During the Session**

   * AI handles initial responses
   * Human agents can join when needed
   * Files and information can be shared
   * System actions can be triggered

3. **Session End**
   * Customer's inquiry is resolved
   * Session is marked as complete
   * Summary and insights are generated

## Session Custom Data

Use top-level `custom_data` on [Create Session](/api-reference/chat-sessions/create) or [Send Message](/api-reference/chat-sessions/send) for attributes that belong to the session, such as an order ID, cart value, or routing flag. Use `contact.custom_data` for attributes that belong to the contact, such as plan, region, or account tier.

Both can be sent in one request:

```json theme={"dark"}
{
  "sender": "contact",
  "custom_data": { "order_id": "ord_123", "priority": "high" },
  "contact": { "custom_data": { "plan": "pro" } },
  "message": { "type": "text", "text": "I need help with this order" }
}
```

## Available Endpoints

<CardGroup>
  <Card title="Create Session" icon="plus" href="/api-reference/chat-sessions/create">
    Start a new chat session
  </Card>

  <Card title="Get Session" icon="magnifying-glass" href="/api-reference/chat-sessions/get">
    Retrieve session details
  </Card>

  <Card title="List Sessions" icon="list" href="/api-reference/chat-sessions/list">
    View all sessions
  </Card>

  <Card title="Update Session" icon="pen" href="/api-reference/chat-sessions/update">
    Modify session information
  </Card>

  <Card title="Assign Session" icon="user-check" href="/api-reference/chat-sessions/assignee">
    Assign a session to a teammate, or unassign it
  </Card>

  <Card title="Transfer to Team" icon="users" href="/api-reference/chat-sessions/team">
    Move a session to another team
  </Card>

  <Card title="Add Tag" icon="tag" href="/api-reference/chat-sessions/add_tag">
    Tag a session, synced to your ticketing system
  </Card>

  <Card title="Send Message" icon="paper-plane" href="/api-reference/chat-sessions/send">
    Send a message in a session
  </Card>

  <Card title="Create Comment" icon="note-sticky" href="/api-reference/chat-sessions/create_comment">
    Add an internal note, visible to agents only
  </Card>

  <Card title="Export Session Events" icon="list" href="/api-reference/chat-sessions/list_events">
    Export activity across your organization with date and event-type filters
  </Card>

  <Card title="Session History" icon="list" href="/api-reference/chat-sessions/list_history">
    View session message history
  </Card>
</CardGroup>


# List chat sessions
Source: https://docs.open.cx/api-reference/chat-sessions/list

get /chat/sessions
Returns a paginated list of chat sessions for the organization. Use when orchestrating conversations from code — creating sessions, sending messages, or listing history for an…

Each session includes `tags`, with each tag's `tag_name` and `created_at` timestamp.
Tags are ordered by name. Sessions without tags return an empty array.

The `support_team` field contains the assigned support team's `id` and `name`.
The ID remains stable when the team is renamed. This field is `null` when no
support team can be resolved for the session.

The `first_human_message_at` field contains the first recorded human reply time as an
ISO 8601 timestamp, or `null` when no human reply has been recorded. Internal notes
and automated messages do not set this timestamp. Later human replies do not change it.

The `title` field is the session title: the email subject, a subject set by an agent,
or an AI-generated title. It is `null` until one is set.

Use `assignee` to identify who is currently assigned to a session:

| Type | Example | Meaning |
| - | - | - |
| Human | `{"type":"human","id":77,"name":"Alex Smith"}` | The numeric ID matches `GET /users`. |
| AI | `{"type":"ai"}` | AI is assigned; no ID or name is returned. |
| None | `{"type":"none"}` | The session is unassigned. |

A human assignee's `name` matches the organization display name in `GET /users`.
An organization name override takes precedence; a blank or missing override falls
back to the account name. The name is `null` if the user is no
longer a member of the organization or cannot be found; the recorded ID remains
available for historical attribution. Reading a session does not require the
`users:read` scope. Reading the user directory, including emails, does.

The response field `assignee_id` is deprecated. Human IDs remain strings there;
AI and unassigned sessions return `null`. Clients that previously used the AI
placeholder must switch to `assignee.type`. Assignment requests continue to use
`assignee_id` with a numeric human user ID or `null` to unassign.


# Export session events
Source: https://docs.open.cx/api-reference/chat-sessions/list_events

get /chat/sessions/events
Pull recorded events across all sessions for reporting and periodic syncs, with optional date ranges, message type filters, and cursor pagination.

Export recorded activity across all sessions in your organization, including
messages, internal notes, and system events. Requires an API key with
`chat-sessions:read`.

Use `created_after` and `created_before` to select a date window. Both accept
ISO 8601 timestamps with a timezone and are optional. The lower bound is inclusive;
the upper bound is exclusive and must be later than the lower bound.

Use `include_message_types` to select recorded types, such as
`agent_reopened_session,agent_comment`, or `exclude_message_types` to omit types,
such as `message,agent_message`. Both accept comma-separated values.
`include_message_types` takes precedence when both are provided. With neither
filter, all recorded types are returned.

Results are ordered oldest first by `created_at`, then by event `id` when
timestamps match. The default `limit` is 100 events; it accepts whole numbers
from 1 to 250. Pass the response's `next` value as `cursor` to continue, keeping
the same organization, date window, and type filters until `next` is `null`.
Deduplicate overlapping exports by event `id`.

Each item uses the same `id`, `created_at`, and typed `event` format as
[session history](/api-reference/chat-sessions/list_history), with `session_id`,
`contact_id`, `message_type`, `actor`, and `details` added for exports.
The session and contact IDs can be `null` when unavailable.

Filter on `message_type`, which is the recorded type. It can differ from the
normalized `event.type`. For example, `agent_reopened_session` can return
`{"type":"human_agent_reopened_session","human_agent_id":77}` in `event`.

Use `actor` to identify who performed the action:

| Type | Identifier |
| - | - |
| `human` | Human user ID in `actor.id`, as a string. Typed event payloads can use numeric human IDs. |
| `contact` | Contact ID when recorded. |
| `workflow` | Workflow ID and `workflow_run_id` when recorded. |
| `ai` | AI actor; no human user ID. |
| `api`, `system`, `integration` | Source of the recorded action. |
| `unknown` | The historical actor could not be identified. |

The assignment recipient is separate from the actor: `details.target` describes
a `human`, `ai`, `team`, or `none` target with an optional string `id`.
`details` also contains recorded message text, `sub_status_id`, `workflow_id`,
`workflow_run_id`, `edited_at`, and `deleted_at`. Unavailable values are `null`.

Events without a history mapping are retained as `event.type: "unmapped_event"`,
with their recorded `message_type` and text `content` when available.
State checkpoint events return `payload: null`.

Date filters use the original event time, including microsecond precision.
Historical imports can arrive later, and edits do not change the original
creation time. Re-export earlier windows to reconcile late imports and edits.
This endpoint exports recorded history; it does not capture every session or
contact attribute change or reconstruct missing historical identities.


# List chat session history
Source: https://docs.open.cx/api-reference/chat-sessions/list_history

get /chat/sessions/{session_id}/history
Returns a paginated list of events (messages, handoffs, status changes, etc.) for a chat session.



# Remove a tag from a chat session
Source: https://docs.open.cx/api-reference/chat-sessions/remove_tag

delete /chat/sessions/{session_id}/tags/{tag_name}
Remove a tag from a session, and from the underlying ticketing system when one is connected.



# Search contacts and messages
Source: https://docs.open.cx/api-reference/chat-sessions/search

get /chat/sessions/search
Full-text search across contacts (by name, email, phone) and chat messages. Use when orchestrating conversations from code — creating sessions, sending messages, or listing…



# Send a message
Source: https://docs.open.cx/api-reference/chat-sessions/send

post /chat/sessions/{session_id}/send
Send a message — Sends a message in a chat session. Use when orchestrating conversations from code — creating sessions, sending messages, or listing history for an external…

## Custom data

This endpoint accepts two independent `custom_data` objects, each merged into a different record:

* **Top-level `custom_data`** — session-level attributes that belong to this conversation, such as an order ID, cart value, or routing flag. Merged into the chat session and returned by [Get Session](/api-reference/chat-sessions/get). Values can be strings, numbers, or booleans.
* **`contact.custom_data`** — contact-level attributes that belong to the person, such as plan, region, or account tier. Merged into the contact. Values are strings.

Both merge into any existing data, so you only need to send the keys you want to add or update. Nested objects are rejected with a `400`.

```json theme={"dark"}
{
  "sender": "contact",
  "custom_data": { "order_id": "ord_123", "cart_value": 149.99, "priority": "high" },
  "contact": { "custom_data": { "plan": "pro", "region": "emea" } },
  "message": { "type": "text", "text": "I need help with this order" }
}
```

<Note>
  Session `custom_data` set through this endpoint is stored on the session but is **not** synced to a connected external ticketing system (e.g. Intercom or HubSpot).
</Note>

## Option taps

An agent reply sent from a macro with options carries them on the [`conversation.agent_response`](/api-reference/webhooks/types) webhook as `options`, next to the reply's `message_id`, and on the message's `event.options` in [session history](/api-reference/chat-sessions/list_history). On API sessions your client renders them. When the customer taps one, send a contact message that names the tap in `message.option_reply`. The message is recorded with the option's label as its text, and an option that isn't on a message of this session is rejected with a `400`:

```json theme={"dark"}
{
  "sender": "contact",
  "message": {
    "type": "text",
    "text": "Yes",
    "option_reply": {
      "message_id": "7c3f1a7e-2a51-4b8e-9d0f-6f1b2c3d4e5f",
      "option_id": "b1e2c3d4-0000-4a5b-8c9d-112233445566"
    }
  }
}
```

Only the first tap on the session's newest message with options counts, and only while the session is open. A tap on a `workflow` option runs the macro's **Macro Option Clicked** workflows and the AI doesn't reply; a `text` option is handled like any contact message. A tap that doesn't count, and the same text sent without `option_reply`, is handled as a normal message. `option_reply` is rejected with a `400` when `sender` is `agent`.


# Clear the custom status of a chat session
Source: https://docs.open.cx/api-reference/chat-sessions/sub_status_clear

delete /chat/sessions/{session_id}/sub-status
Remove the custom status from a session while leaving its built-in status untouched. Clearing on a closed session neither reopens nor re-closes it.



# Set the custom status of a chat session
Source: https://docs.open.cx/api-reference/chat-sessions/sub_status_set

put /chat/sessions/{session_id}/sub-status
Apply a custom status to a session. The session moves to that status's built-in parent, so an open-parented status reopens a closed session and a closed-parented one closes it.

Applying a custom status whose parent is `closed_resolved` closes the session the same way as [updating its status](/api-reference/chat-sessions/update#ai-outcome-on-close), including the AI outcome it records.


# Transfer a chat session to a team
Source: https://docs.open.cx/api-reference/chat-sessions/team

post /chat/sessions/{session_id}/team
Transfer a session to a team. Open routes to an available member of that team when one is free, so this both transfers and assigns. Use `GET /teams` to look up team IDs.



# Update a chat session
Source: https://docs.open.cx/api-reference/chat-sessions/update

patch /chat/sessions/{session_id}
Update a chat session — Updates a chat session. Use when orchestrating conversations from code — creating sessions, sending messages, or listing history for an external surface.

Send `summary` to replace the session's summary, for example with notes from a system that handled part of the conversation. Send `null` to clear it. A summary-only update leaves the status unchanged. When the same request closes the session with `generate_summary_and_sentiment_on_resolve`, the `summary` you send is kept instead of the generated one.

## AI outcome on close

Closing a session as `closed_resolved` while the AI agent owns it outside assist mode records the AI outcome `assumed_resolved`, provided the AI agent replied and no teammate replied or took the session over. The outcome counts toward the AI resolutions in your impact report and is passed to `ticket-resolved` workflows. Voice and internal sessions are left unchanged. A `closed_unresolved` close never records an AI outcome, reclosing or retrying a close keeps the outcome already on the session, and a session closed as unresolved is not marked as an AI resolution when it is later changed to resolved. Each close is written to the audit log with the API key that made it.


# Update a session comment
Source: https://docs.open.cx/api-reference/chat-sessions/update_comment

patch /chat/sessions/{session_id}/comments/{comment_uuid}
Update a session comment — Replaces the content of an internal note and stamps it as edited. Only the agent who authored the note may edit it.

Replaces the content of an existing internal note and stamps it as edited.

Only the note's **author** may edit it: `agent_id` must match the agent the note is attributed to, otherwise the request is rejected with a `403`. A note that has been deleted can no longer be edited.

<Note>
  `agent_id` identifies who the edit is attributed to — it is not a credential. An API key is scoped to the organization, not to one agent, so treat this rule as a safeguard against editing the wrong agent's note rather than as a permission boundary between your own agents.
</Note>

```json theme={"dark"}
{
  "content": "Correction: the refund was issued on the 14th, not the 12th.",
  "agent_id": 42
}
```

The note is resolved against the session in the path, so a `comment_uuid` belonging to a different session returns a `404` rather than editing the wrong conversation.

## Attachments

`attachments` is a full replacement of the note's file list, not a patch:

| You send | Result |
| - | - |
| No `attachments` field | Existing files are kept as they are |
| `"attachments": []` | All files are removed from the note |
| `"attachments": [...]` | The list you send replaces the existing files |

So editing only the wording is safe — omit the field and the files stay put. To drop a single file, send the list of the ones you want to keep.


# Link many contacts to companies
Source: https://docs.open.cx/api-reference/companies/bulk-link

post /companies/links
Link up to 100 contacts to companies in one call, naming each contact by id, email, or phone. A row that fails returns its own error and does not affect the others.



# Retrieve a company
Source: https://docs.open.cx/api-reference/companies/get

get /companies/{company_id}
Retrieve one company by its OpenCX id, with its name, your own external ID, and its attributes. Use when you already hold a company ID.



# Introduction to companies
Source: https://docs.open.cx/api-reference/companies/introduction

Group contacts under the company they belong to, and attach the account data your agents need during a conversation.

## What is a company?

A **company** is an account record that contacts belong to. If three people from Acme Retail open sessions, they can all point at one Acme Retail company instead of each carrying their own copy of the plan tier, the CSM's name, and the account id.

A contact can belong to several companies, and a company can have any number of contacts.

## Identity is your key, not ours

Every company is identified by `external_id` — whatever you already call it in your own system. A Zoho account id, a merchant id, a tenant slug. Writes resolve on that key, so the same `POST /companies` call creates the company the first time and updates it every time after.

`name` is for display only. It is not unique, so two merchants can both be called "Acme" and renaming one is never a collision.

## What you can do

* **Create or update a company** → [Upsert a company](/api-reference/companies/upsert)
* **Find companies by owner, attribute, or name** → [Search companies](/api-reference/companies/search)
* **Assign the teammate who owns it** → [Set the owner](/api-reference/companies/set-owner)
* **Add a company to a contact** → [Link a contact](/api-reference/contacts/companies/link)
* **Read a contact's companies** → [List a contact's companies](/api-reference/contacts/companies/list)
* **Remove one company from a contact** → [Unlink a contact](/api-reference/contacts/companies/unlink)

Linking is strict: the `external_id` must already exist. An unknown key returns a 400 rather than creating a company, so a typo in a sync script cannot quietly fill your account list with junk.

## Attributes

`custom_data` holds flat key/value attributes — strings, numbers, and booleans. Sending an attribute merges it into what is already there, and sending it as `null` clears that one key. Keys you do not mention are left alone.

```json theme={"dark"}
{
  "external_id": "acct_88213",
  "name": "Acme Retail",
  "custom_data": { "plan": "growth", "seats": 40, "csm": "sara@acme.test" }
}
```

<Note>
  Company attributes are not visible to the AI agent. They are available to your
  workflows through the **Get Contact Companies** action, and to your agents in
  the inbox, but they are never added to the model's prompt.
</Note>

## Who owns the account

A company can name one teammate as its owner, the CSM or account manager who looks after it. The owner shows on the company's page and on the companies card in the inbox, so an agent picking up a session can see who to ask.

Name the owner by OpenCX user id or by email, whichever you already hold:

```json theme={"dark"}
{ "owner": { "email": "sara@yourcompany.test" } }
```

Email matching ignores capitalization, so an address copied straight out of a CRM works. Send `"owner": null` to leave the company unowned, which is the state every company starts in.

You can set the owner while creating the company, in the same [upsert](/api-reference/companies/upsert) call:

```json theme={"dark"}
{
  "external_id": "acct_88213",
  "name": "Acme Retail",
  "owner": { "email": "sara@yourcompany.test" }
}
```

Omitting `owner` leaves ownership alone, so a nightly attribute sync never reassigns an account by accident.

The owner must be a member of your organization. An email that belongs to nobody on your team returns a 400 rather than quietly clearing the field. The error reads the same whether the address is unknown to OpenCX or belongs to another organization, so it tells you nothing about who exists outside your own team.

When a teammate leaves your organization, every company they owned becomes unowned.

## Syncing from a CRM

A CRM sync usually pushes many links at once. [Link many contacts](/api-reference/companies/bulk-link) takes up to 100 in a single call and isolates failures: a row naming a company that was never created returns its own error, and the other 99 links still land. Results come back in request order with a summary.

Name each contact whichever way you already hold it — `contact_id`, `contact_email`, or `contact_phone`, exactly one per row — so you don't have to resolve every contact to an OpenCX id first. Each result carries the resolved `contact_id`, which is worth storing against your own record to skip the lookup next time.

```json theme={"dark"}
{
  "links": [
    { "contact_email": "sara@acme.test", "external_id": "acct_88213" },
    { "contact_phone": "+15551234567", "external_id": "acct_88213" },
    { "contact_id": "8f3c...", "external_id": "acct_44100" }
  ]
}
```

Phone matching is forgiving about spelling: `+15551234567` and `15551234567` find the same contact. If a number matches more than one contact, that row reports an error instead of guessing — name that contact by `contact_id`.

## Scopes

Reads need `companies:read`; writes need `companies:write`.

These are separate from `contacts:*` on purpose. Company records usually carry data pulled from your CRM, so a key that manages contacts does not automatically get to read or rewrite the account graph.

## Companies in workflows

Five workflow actions cover the same ground without any API calls:

* **Create or Update Company**
* **Link Contact to Company**
* **Get Contact Companies** — returns `found`, `count`, and the list, so you can branch on a contact having no company
* **Set Company Owner** — takes an email or an agent id, so a workflow can assign the owner from a CRM lookup
* **Unlink Contact from Company** — removes one company and leaves the contact's others alone

Get Contact Companies returns each company's owner as `agentOwnerId`, `agentOwnerName`, and `agentOwnerEmail`. The id is the same numeric agent id **Change Ticket Assignee** takes, so a workflow can route a session to whoever owns the account. Check `agentOwnerId` is set before assigning, since most companies have no owner.

Linking a contact does not fire the **Contact Updated** trigger. Nothing on the contact record changes, and a workflow that links on Contact Updated would otherwise re-trigger itself.


# List companies
Source: https://docs.open.cx/api-reference/companies/list

get /companies
Page through every company in your organization, newest first. Use to browse the account list or reconcile it against your own CRM.



# Search companies
Source: https://docs.open.cx/api-reference/companies/search

post /companies/search
Find companies by the teammate who owns them, by attribute conditions such as a plan or a subscription date, or by name, sorted and paged.

Every filter you send must hold, so each one narrows the result. Leave `filters` out to page through every company.

```json theme={"dark"}
{
  "filters": {
    "owner_ids": [12],
    "custom_data": [
      { "key": "plan", "op": "eq", "value": "enterprise" },
      { "key": "subscriptionStart", "op": "after", "value": "2025-03-01" }
    ]
  },
  "search": "acme",
  "ordering": { "field": "contacts_count", "direction": "desc" },
  "page": 1,
  "limit": 50
}
```

## Owner

`owner_ids` matches companies owned by any of the listed teammates. `unowned: true` matches companies nobody owns. Send both to get "these teammates' companies, plus the unowned ones".

## Attribute conditions

| `op` | Matches when the attribute… | `value` |
| - | - | - |
| `exists` / `not_exists` | is set / is not set | — |
| `eq` / `neq` | equals / does not equal the value | text |
| `contains` | contains the value, ignoring case | text |
| `before` / `after` | is a date earlier / later than the day | `YYYY-MM-DD` |

`eq` also matches numbers and booleans, so `"value": "40"` finds a `seats` attribute stored as `40`.

`before` and `after` read the attribute as a date when it holds a whole ISO 8601 date or timestamp (`"2025-03-14"`, `"2025-03-14T09:30:00Z"`, `"2025-03-14T09:30:00+03:00"`) or a Unix timestamp. Dates are compared by UTC day: a timestamp with an offset counts on its UTC day, and one without an offset is read as UTC. The day you send matches neither side, so `after 2025-03-01` starts on March 2.

A number above 100,000,000,000 is read as milliseconds, anything smaller as seconds. An attribute in any other format, such as `"14/03/2025"` or `"2025-03-14 approx"`, never matches a date condition.

## Scopes

Needs `companies:read`.


# Set a company's owning teammate
Source: https://docs.open.cx/api-reference/companies/set-owner

put /companies/{external_id}/owner
Assign the teammate who owns a company account, naming them by OpenCX user id or by email, or clear the owner to leave the account unassigned.



# Create or update a company
Source: https://docs.open.cx/api-reference/companies/upsert

post /companies
Create a company, or update it if the external_id already exists. Attributes merge into the existing record, and you can set the owner in the same call.



# Add a Connect participant
Source: https://docs.open.cx/api-reference/connect/add-participant

POST /connect/threads/{thread_id}/participants
Add a participant to a thread — typically the courier at assignment time. Waiting lanes for their role activate automatically on join.

Add a participant to an open thread. The standard use is adding the `courier` at assignment — the `customer_courier` lane flips from `waiting` to `active` and the Supervisor briefs the courier with any context that matters ("leave at the gate, code 4411").

A thread holds one active participant per role; adding a second courier returns `409` — [remove](/api-reference/connect/remove-participant) the first for reassignment.

## Path

<ParamField type="string">
  Thread ID (`th_…`) or your `reference`.
</ParamField>

## Request

<ParamField type="string">
  `customer`, `merchant`, or `courier`.
</ParamField>

<ParamField type="string">
  Your ID for this person.
</ParamField>

<ParamField type="string">
  Name shown to other participants.
</ParamField>

<ParamField type="string">
  BCP-47 code for this participant's reading language.
</ParamField>

## Response

<ResponseField name="participant" type="object">
  The created participant with server ID (`prt_…`).
</ResponseField>

<ResponseField name="lanes" type="array">
  Updated lane states — the joining role's lanes become `active`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.open.cx/connect/threads/order_84421/participants \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "role": "courier", "external_id": "drv_318",
          "display_name": "Aleksei", "language": "en" }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"dark"}
  {
    "participant": { "id": "prt_d55", "role": "courier", "external_id": "drv_318",
                     "display_name": "Aleksei", "language": "en" },
    "lanes": [
      { "id": "customer_merchant", "status": "active" },
      { "id": "customer_courier", "status": "active" }
    ]
  }
  ```
</ResponseExample>


# Create a Connect thread
Source: https://docs.open.cx/api-reference/connect/create-thread

POST /connect/threads
Create an order-scoped thread with its initial participants. Idempotent on reference, so call it from your order pipeline without duplicate-guarding.

Create the conversation for an order. Call it when the order is confirmed — the `customer_merchant` lane opens immediately; the `customer_courier` lane waits for a courier.

## Request

<ParamField type="string">
  Your order ID. Unique per organization and the idempotency key: posting an existing `reference` returns the existing thread with `200`.
</ParamField>

<ParamField type="array">
  Initial participants. Usually the customer and merchant; couriers are [added later](/api-reference/connect/add-participant).

  <Expandable title="participant">
    <ParamField type="string">
      `customer`, `merchant`, or `courier`.
    </ParamField>

    <ParamField type="string">
      Your ID for this person or store. Also accepts an OpenCX `contact_id` for customers already known to your workspace.
    </ParamField>

    <ParamField type="string">
      Name shown to the other participants. Never expose contact details here.
    </ParamField>

    <ParamField type="string">
      BCP-47 code (`ar`, `en`, `hi`…). The Supervisor renders every message in this language for this participant. Defaults to your org's primary language.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="array">
  Lanes to enable. Defaults to `["customer_merchant", "customer_courier"]`; include `"merchant_courier"` to open the third lane.
</ParamField>

<ParamField type="object">
  Override the org-default [Supervisor](/connect/ai-supervisor) config for this thread.

  <Expandable title="supervisor">
    <ParamField type="string">
      `observe`, `assist`, or `resolve` (org default applies when omitted).
    </ParamField>

    <ParamField type="object">
      Per-lane overrides: `{ "customer_courier": { "mode": "assist", "nudge_after_seconds": 300 } }`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Override org defaults: `wrap_up_hours` (default `24`), `retention_days` (days after locking before the thread is archived; not set by default, so a locked thread stays locked until you set it). Archiving never deletes thread history.
</ParamField>

<ParamField type="object">
  Arbitrary JSON stored on the thread and surfaced to the Supervisor as answering context — order total, vertical, promo flags.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Thread ID (`th_…`).
</ResponseField>

<ResponseField name="reference" type="string">
  Your order ID.
</ResponseField>

<ResponseField name="status" type="string">
  `open` on creation. Lifecycle: `open → wrap_up → locked → archived`.
</ResponseField>

<ResponseField name="order_status" type="string">
  Starts at `confirmed`; you drive it via [Update thread](/api-reference/connect/update-thread).
</ResponseField>

<ResponseField name="participants" type="array">
  Participants with server-assigned `id` (`prt_…`) alongside your `external_id`.
</ResponseField>

<ResponseField name="lanes" type="array">
  Lane objects: `id`, `status` (`active` | `waiting` | `closed`), `supervisor_mode`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.open.cx/connect/threads \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "reference": "order_84421",
      "participants": [
        { "role": "customer", "external_id": "cus_991",
          "display_name": "Fatima", "language": "ar" },
        { "role": "merchant", "external_id": "mrc_204",
          "display_name": "Shawarma House", "language": "en" }
      ],
      "custom_data": { "vertical": "food", "total": 86.5, "currency": "QAR" }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"dark"}
  {
    "id": "th_9f2c4e",
    "reference": "order_84421",
    "status": "open",
    "order_status": "confirmed",
    "participants": [
      { "id": "prt_c81", "role": "customer", "external_id": "cus_991",
        "display_name": "Fatima", "language": "ar" },
      { "id": "prt_m32", "role": "merchant", "external_id": "mrc_204",
        "display_name": "Shawarma House", "language": "en" }
    ],
    "lanes": [
      { "id": "customer_merchant", "status": "active", "supervisor_mode": "resolve" },
      { "id": "customer_courier", "status": "waiting", "supervisor_mode": "resolve" }
    ],
    "custom_data": { "vertical": "food", "total": 86.5, "currency": "QAR" },
    "created_at": "2026-07-30T14:03:11Z"
  }
  ```
</ResponseExample>


# Create a participant token
Source: https://docs.open.cx/api-reference/connect/create-token

POST /connect/threads/{thread_id}/tokens
Mint a short-lived scoped token for one participant to power the drop-in thread component or a headless WebSocket — their lanes and language only.

Mint a client token for one participant. Pass it to the `<ConnectThread>` component or use it to open the thread WebSocket for a custom UI. The token grants exactly that participant's view: their lanes, their language, read/send only while the thread accepts messages.

Tokens expire after 24 hours by default — mint them server-side when your app opens the order screen, not at order creation.

## Path

<ParamField type="string">
  Thread ID (`th_…`) or your `reference`.
</ParamField>

## Request

<ParamField type="string">
  Participant ID (`prt_…`) or their `external_id`.
</ParamField>

<ParamField type="number">
  Token lifetime, max 7 days.
</ParamField>

## Response

<ResponseField name="token" type="string">
  The scoped participant token.
</ResponseField>

<ResponseField name="expires_at" type="string">
  ISO 8601 expiry.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.open.cx/connect/threads/order_84421/tokens \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "participant_id": "cus_991" }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"dark"}
  {
    "token": "cntk_eyJhbGciOiJIUzI1NiJ9...",
    "expires_at": "2026-07-31T14:05:00Z"
  }
  ```
</ResponseExample>


# Get a Connect thread
Source: https://docs.open.cx/api-reference/connect/get-thread

GET /connect/threads/{thread_id}
Fetch one thread by ID or by your order reference — participants, lanes, lifecycle status, Supervisor config, and custom data in a single read.

Fetch a single thread. Accepts either the thread ID (`th_…`) or your order reference — `GET /connect/threads/order_84421` resolves the same thread, so you never store our IDs if you don't want to.

## Path

<ParamField type="string">
  Thread ID (`th_…`) or your `reference` (order ID).
</ParamField>

## Response

The full thread object — same shape as [Create thread](/api-reference/connect/create-thread), plus live lane state and counters.

<ResponseField name="message_counts" type="object">
  Per-lane message totals, including `supervisor` messages — a quick deflection read without listing messages.
</ResponseField>

<ResponseField name="escalations" type="array">
  Sessions this thread escalated into: `{ session_id, reason, created_at }`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl https://api.open.cx/connect/threads/order_84421 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "id": "th_9f2c4e",
    "reference": "order_84421",
    "status": "wrap_up",
    "order_status": "delivered",
    "participants": [
      { "id": "prt_c81", "role": "customer", "display_name": "Fatima", "language": "ar" },
      { "id": "prt_m32", "role": "merchant", "display_name": "Shawarma House", "language": "en" },
      { "id": "prt_d55", "role": "courier", "display_name": "Aleksei", "language": "en" }
    ],
    "lanes": [
      { "id": "customer_merchant", "status": "active", "supervisor_mode": "resolve" },
      { "id": "customer_courier", "status": "active", "supervisor_mode": "resolve" }
    ],
    "message_counts": { "customer_merchant": 6, "customer_courier": 4, "supervisor": 3 },
    "escalations": [],
    "created_at": "2026-07-30T14:03:11Z"
  }
  ```
</ResponseExample>


# Connect API overview
Source: https://docs.open.cx/api-reference/connect/index

REST reference for Connect: order-scoped threads with customer, merchant, and courier participants, lane-scoped messages, participant tokens, and lifecycle updates.

The Connect API manages **threads** — order-scoped conversations between a `customer`, a `merchant`, and a `courier`, supervised by your AI agent. Concepts are covered in the [Connect overview](/connect/introduction); this section is the REST surface.

All endpoints live under `https://api.open.cx/connect` and use [Bearer authentication](/api-reference/authentication).

## Resources

| Resource | Endpoints |
| - | - |
| Threads | [Create](/api-reference/connect/create-thread) · [Get](/api-reference/connect/get-thread) · [List](/api-reference/connect/list-threads) · [Update](/api-reference/connect/update-thread) |
| Participants | [Add](/api-reference/connect/add-participant) · [Remove](/api-reference/connect/remove-participant) · [Create token](/api-reference/connect/create-token) |
| Messages | [Send](/api-reference/connect/send-message) · [List](/api-reference/connect/list-messages) |

## The two calls that matter

A full integration is thread creation at order confirmation and participant addition at courier assignment — the lifecycle, translation, moderation, and AI resolution run on their own. Everything else here exists for headless UIs, ops tooling, and audit.

## Idempotency

`POST /connect/threads` is idempotent on `reference` (your order ID): repeat calls return the existing thread with `200` instead of creating a duplicate. Design your order pipeline to fire-and-retry safely.


# List Connect messages
Source: https://docs.open.cx/api-reference/connect/list-messages

GET /connect/threads/{thread_id}/messages
Page through a thread’s messages and events — filter by lane, include Supervisor interventions, and export full conversation history for audits and disputes.

List a thread's messages, oldest first, cursor-paginated. Includes participant messages, system chips, and Supervisor messages — the complete record of the order conversation.

## Path

<ParamField type="string">
  Thread ID (`th_…`) or your `reference`.
</ParamField>

## Query

<ParamField type="string">
  Restrict to one lane.
</ParamField>

<ParamField type="boolean">
  Interleave non-message events (joins, removals, status changes, safety masks) as typed entries — the full audit trail for disputes.
</ParamField>

<ParamField type="string">
  Cursor from a previous response.
</ParamField>

<ParamField type="number">
  Page size, max 200.
</ParamField>

## Response

<ResponseField name="data" type="array">
  Message objects (same shape as [Send message](/api-reference/connect/send-message)); event entries carry `type` instead of `sender` when `include_events` is set.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Present when more results exist.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl "https://api.open.cx/connect/threads/order_84421/messages?lane=customer_courier&include_events=true" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "data": [
      { "id": "msg_1q8x", "lane": "customer_courier",
        "sender": { "participant_id": "prt_c81", "role": "customer" },
        "text": "البوابة رقم ٤ — الرمز 4411",
        "translations": { "en": "Gate 4 — the code is 4411" },
        "created_at": "2026-07-30T14:31:05Z" },
      { "id": "evt_9k2m", "type": "supervisor.safety_mask", "lane": "customer_courier",
        "detail": "Masked a phone number in an outbound courier message",
        "created_at": "2026-07-30T14:33:47Z" }
    ],
    "next_cursor": null
  }
  ```
</ResponseExample>


# List Connect threads
Source: https://docs.open.cx/api-reference/connect/list-threads

GET /connect/threads
Page through threads filtered by status, order status, participant, or date range. Use for ops dashboards, dispute lookups, and archive queries.

List threads for your organization, newest first, cursor-paginated.

## Query

<ParamField type="string">
  Filter by lifecycle status: `open`, `wrap_up`, `locked`, `archived`.
</ParamField>

<ParamField type="string">
  Filter by the order status you last reported (`confirmed`, `picked_up`, `delivered`…).
</ParamField>

<ParamField type="string">
  Threads that include this participant — every conversation a given courier or merchant has been part of.
</ParamField>

<ParamField type="boolean">
  Only threads that escalated into a support session.
</ParamField>

<ParamField type="string">
  ISO 8601 lower bound on creation time.
</ParamField>

<ParamField type="string">
  Cursor from a previous response.
</ParamField>

<ParamField type="number">
  Page size, max 100.
</ParamField>

## Response

<ResponseField name="data" type="array">
  Thread objects (same shape as [Get thread](/api-reference/connect/get-thread)).
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Present when more results exist.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl "https://api.open.cx/connect/threads?status=open&escalated=true&limit=50" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "data": [
      { "id": "th_9f2c4e", "reference": "order_84421", "status": "open",
        "order_status": "picked_up", "escalations": [{ "session_id": "ses_77a1", "reason": "sentiment", "created_at": "2026-07-30T14:41:02Z" }] }
    ],
    "next_cursor": "eyJvZmZzZXQiOjUwfQ"
  }
  ```
</ResponseExample>


# Remove a Connect participant
Source: https://docs.open.cx/api-reference/connect/remove-participant

DELETE /connect/threads/{thread_id}/participants/{participant_id}
Remove a participant from a thread — courier reassignment being the common case. Access is revoked instantly; lane history stays with the thread.

Remove a participant. Their tokens are revoked immediately and their apps lose the thread; the lane's history remains for the other side and for audit. The lane returns to `waiting` until a replacement joins.

## Path

<ParamField type="string">
  Thread ID (`th_…`) or your `reference`.
</ParamField>

<ParamField type="string">
  Participant ID (`prt_…`) or their `external_id`.
</ParamField>

## Response

<ResponseField name="removed" type="boolean">
  Always `true` on success.
</ResponseField>

<ResponseField name="lanes" type="array">
  Updated lane states.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X DELETE https://api.open.cx/connect/threads/order_84421/participants/drv_318 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "removed": true,
    "lanes": [
      { "id": "customer_merchant", "status": "active" },
      { "id": "customer_courier", "status": "waiting" }
    ]
  }
  ```
</ResponseExample>


# Send a Connect message
Source: https://docs.open.cx/api-reference/connect/send-message

POST /connect/threads/{thread_id}/messages
Send a message into a lane on behalf of a participant — the server-side path for headless UIs and system notices. Translation and safety run before delivery.

Send a message into a lane on behalf of a participant. This is the headless path — apps using the drop-in component send through their [participant token](/api-reference/connect/create-token) instead.

Every message passes through the Supervisor's pipeline before delivery: safety masking, then translation into each recipient's language. Sending into a `locked` thread returns `409`.

## Path

<ParamField type="string">
  Thread ID (`th_…`) or your `reference`.
</ParamField>

## Request

<ParamField type="string">
  Sender — participant ID (`prt_…`) or their `external_id`. Use `"system"` for order-event notices ("Your order was picked up"), rendered as system chips, not chat bubbles.
</ParamField>

<ParamField type="string">
  `customer_merchant`, `customer_courier`, or `merchant_courier`. The sender's role must belong to the lane.
</ParamField>

<ParamField type="string">
  Message text. Required unless `attachments` is present.
</ParamField>

<ParamField type="array">
  Files by URL: `[{ "url": "https://…", "content_type": "image/jpeg" }]`.
</ParamField>

## Response

<ResponseField name="message" type="object">
  The created message, including `translations` keyed by language and the post-masking `text`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.open.cx/connect/threads/order_84421/messages \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "participant_id": "mrc_204",
      "lane": "customer_merchant",
      "text": "Out of garlic sauce — swap for tahini or refund the item?"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"dark"}
  {
    "message": {
      "id": "msg_4t1a",
      "lane": "customer_merchant",
      "sender": { "participant_id": "prt_m32", "role": "merchant" },
      "text": "Out of garlic sauce — swap for tahini or refund the item?",
      "translations": {
        "ar": "نفدت صلصة الثوم — نستبدلها بالطحينة أم نسترد قيمة الصنف؟"
      },
      "created_at": "2026-07-30T14:12:40Z"
    }
  }
  ```
</ResponseExample>


# Update a Connect thread
Source: https://docs.open.cx/api-reference/connect/update-thread

PATCH /connect/threads/{thread_id}
Report order status to drive the thread lifecycle, adjust Supervisor modes per lane, or force-lock a thread. The one write you call as the order progresses.

Update a thread as the order progresses. Reporting `order_status` is the normal use — the [lifecycle](/connect/threads) reacts automatically.

## Path

<ParamField type="string">
  Thread ID (`th_…`) or your `reference`.
</ParamField>

## Request

<ParamField type="string">
  `confirmed`, `preparing`, `ready`, `picked_up`, `delivered`, or `cancelled`. `delivered` starts the wrap-up window; `cancelled` locks immediately. Custom statuses pass through to the Supervisor and the UI status chip.
</ParamField>

<ParamField type="string">
  Force a lifecycle transition: `locked` locks now (skips the wrap-up window). Reopening a locked thread is not supported — escalate to a [session](/api-reference/chat-sessions/create) instead.
</ParamField>

<ParamField type="object">
  Same shape as on [create](/api-reference/connect/create-thread): thread- or lane-level `mode`, `nudge_after_seconds`, escalation rules.
</ParamField>

<ParamField type="array">
  Enable an optional lane mid-thread, e.g. `["merchant_courier"]` when a pickup goes sideways.
</ParamField>

<ParamField type="object">
  Merged into existing custom data (top-level keys replace).
</ParamField>

## Response

The updated thread object.

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X PATCH https://api.open.cx/connect/threads/order_84421 \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "order_status": "delivered" }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "id": "th_9f2c4e",
    "reference": "order_84421",
    "status": "wrap_up",
    "order_status": "delivered",
    "wrap_up_ends_at": "2026-07-31T15:20:44Z"
  }
  ```
</ResponseExample>


# Add a company to a contact
Source: https://docs.open.cx/api-reference/contacts/companies/link

post /contacts/{contact_id}/companies
Add an existing company to a contact. Adds rather than replaces, so a contact can belong to several companies.



# List a contact's companies
Source: https://docs.open.cx/api-reference/contacts/companies/list

get /contacts/{contact_id}/companies
List every company a contact belongs to, newest link first. An empty list means the contact belongs to none.



# Remove one company from a contact
Source: https://docs.open.cx/api-reference/contacts/companies/unlink

delete /contacts/{contact_id}/companies/{external_id}
Remove one company from a contact. The contact's other companies stay, and the company record itself is not deleted.



# Create a contact
Source: https://docs.open.cx/api-reference/contacts/create

post /contacts
Create a new contact. Use when your application needs to create, look up, or maintain the contact records that the AI agents converse with.



# Delete a contact
Source: https://docs.open.cx/api-reference/contacts/delete

delete /contacts/{contact_id}
Delete a contact. Use when your application needs to create, look up, or maintain the contact records that the AI agents converse with.



# Get a contact
Source: https://docs.open.cx/api-reference/contacts/get

get /contacts/{contact_id}
Get a single contact by its ID. Use when your application already holds a contact ID and needs that contact's details and custom data.



# Get contact structured field values
Source: https://docs.open.cx/api-reference/contacts/get-structured-field-values

get /contacts/{contact_id}/structured-field-values
Get the Structured Field values recorded on a contact, plus the fields that currently apply to it. Use when your application reads profile facts, such as plan or tier, kept on the contact.



# Introduction to contacts
Source: https://docs.open.cx/api-reference/contacts/introduction

The contact APIs let you create, get, list, update, and delete contacts and read their custom data.

## What is a contact?

A contact is a user that can interact with the chatbot, phone AI or email AI, a single contact might have multiple conversations across different channels.

## How do I create a contact?

You can create a contact in your organization in two ways:

#### 1. Using the API

We have a simple public API that allows you to manage contacts in your organization, you can use the API to [create a contact](/api-reference/contacts/create) or to [authenticate a contact](/api-reference/widget/authenticate-contact).

#### 2. Using the widget

Whenever you embed the copilot widget in your application, you can use the widget options to create a contact, read more about this option in the [widget documentation](/widget/introduction).

### Adding custom data to a contact

You can add any custom data you want to associate with the contact. This data will be returned in the response and can be used for any purpose you want, just make sure it's a valid JSON string object.
The custom data is just a simple JSON object, you can add any key-value pairs you want to it, for example:

```jsx theme={"dark"}
const widgetOptions = {
  initialMessage: "Hello! How can I help you?",
  token: "your_copilot_token_goes_here",
  user: {
    data: {
      name: "your_user_name",
      email: "your_user_email",
      customData: {
        // any custom data you want to send to the copilot backend
        "key1": "value1",
        "balance": 100,
        "age": 25,
      }
    }
  },
```

You can use the API or the widget to add custom data to a contact.

### Reading custom data

[Get a contact](/api-reference/contacts/get), [list contacts](/api-reference/contacts/list) and contact search return two custom data objects:

* `custom_data`: data from verified sources, such as the API or an authenticated widget user.
* `non_verified_custom_data`: data from unverified sources, such as an anonymous widget visitor. It is kept separate so it is never mistaken for trusted data.

These responses include only keys with text values. A key whose value is a number, boolean or nested object is left out of the response, while every other key is still returned. To read a value through the API, store it as text, for example `"balance": "100"`.


# List contacts
Source: https://docs.open.cx/api-reference/contacts/list

get /contacts
List contacts. Use when your application needs to create, look up, or maintain the contact records that the AI agents converse with.



# Check contact segment membership
Source: https://docs.open.cx/api-reference/contacts/segments/check

get /contacts/segments/{segment_id}/contacts/{contact_id}
Check whether a specific contact is a member of a specific segment. Returns a single boolean — useful for gating behavior on cohort membership.



# Create a contact segment
Source: https://docs.open.cx/api-reference/contacts/segments/create

POST /contacts/segments
Create a contact segment through the public API with segment write permission. Learn the request fields, responses, and membership behavior.

Requires `segments:write`.

Supply `name` and `definition`. Omit `description` to use `null`. Membership is calculated in the background. A `null` definition matches all contacts.

See [contact segment guidance](/api-reference/contacts/segments/introduction) for filter examples and membership timing.


# Delete a contact segment
Source: https://docs.open.cx/api-reference/contacts/segments/delete

DELETE /contacts/segments/{segment_id}
Delete a contact segment through the public API with segment write permission. Learn the request fields, responses, and membership behavior.

Requires `segments:write`.

Deletes the definition and its stored memberships, retaining contacts. Returns 204 with no body, or 404 if the segment does not exist in your organization. References in other configurations are not rewritten; review them before deletion.

See [contact segment guidance](/api-reference/contacts/segments/introduction) for filter examples and membership timing.


# Get a contact segment
Source: https://docs.open.cx/api-reference/contacts/segments/get

get /contacts/segments/{segment_id}
Get a single contact segment definition by ID, including the underlying filter rules.



# Introduction to contact segments
Source: https://docs.open.cx/api-reference/contacts/segments/introduction

Create and manage contact segments through the API, then check membership to target the right contacts with rules and personalized support.

## What is a contact segment?

A **contact segment** is a named group of contacts based on rules you define in the dashboard or through the API (for example, "VIP customers" or "Trial users").

OpenCX evaluates those rules in the background and stores membership, so API reads are fast. A contact can belong to multiple segments at once.

## Reading segments from the API

Reading endpoints under `/contacts/segments` requires `segments:read`. They answer four common questions:

* **What segments do I have?** → [List segments](/api-reference/contacts/segments/list)
* **What does this segment look like?** → [Get a segment](/api-reference/contacts/segments/get)
* **Which segments is this contact in?** → [List segments for a contact](/api-reference/contacts/segments/list-for-contact)
* **Is this contact in this specific segment?** → [Check membership](/api-reference/contacts/segments/check)

## Managing segments through the API

Writing requires `segments:write`, independently of `segments:read`:

* [Create a segment](/api-reference/contacts/segments/create) with a name and filter definition. Description is optional and defaults to `null`.
* [Update a segment](/api-reference/contacts/segments/update) by sending only changed fields. A supplied `definition` replaces the entire rule set; it is not merged. Send `description: null` to clear the description.
* [Delete a segment](/api-reference/contacts/segments/delete) to remove its definition and stored memberships. Contacts are retained. Missing segment IDs return 404.

Filter definitions combine `or` groups containing `and` conditions. For example, match contacts whose email domain is `example.com`:

```json theme={"dark"}
{
  "name": "Example customers",
  "definition": {
    "or": [{ "and": [{ "type": "contacts_email_domain_name_in", "domain_name_in": ["example.com"] }] }]
  }
}
```

A `null` definition matches all contacts. An empty `or` list is invalid; an empty `and` group matches all contacts. Creation and filter changes calculate membership in the background, so immediate membership reads may reflect the previous state. Renaming or changing a description does not trigger recalculation.

Deleting a segment does not rewrite references in other segment definitions, actions, instructions, or workflows. Review those references before deletion.

Companion supports creating, updating, and deleting segments for users with contact write permission. MCP clients expose the same operations as `create_contact_segment`, `update_contact_segment`, and `delete_contact_segment`.

## Viewing and editing in the dashboard

Open **Contacts → Segments** to inspect saved segments, including those created through Companion, MCP, or the API. The list shows a condition summary; open it to see the complete definition with its groups.

Name the segment, then choose **Add first condition**. Search for a contact detail, activity, or status. Add a description if useful. Select **Include all contacts** when everyone should belong.

Use **Add condition** to narrow the audience: a contact must satisfy every condition in that section. **Add an alternative** creates another way to qualify, shown as **Or include contacts who…**. For example, one section can include Pro customers in France, and another can include VIP customers anywhere. A contact only needs to qualify for one section.

For lists of names, email addresses, email domains, phone numbers, or contact IDs, use **Add value** for each additional entry. Each field is one value; line breaks inside a saved value stay part of that value.

For new **Contact attributes** conditions, select an attribute name and an operator: **equals**, **not equals**, **contains**, **exists**, or **not exists**. Only comparison operators need a value. Use **Add attribute** to require another attribute to match. This is the single option for filtering saved contact fields, such as plan or country. Existing equality-only conditions remain editable with their saved grouping and matching behavior.

**Session attributes** is separate: it matches attributes saved on a contact's sessions, using exact key/value matches. Other condition types retain their own matching behavior; the five contact-attribute operators do not apply to every field.

Existing contact and session attribute alternatives keep their original grouping, including untouched empty alternatives when you edit another alternative. Dates retain saved bounds and precision until edited; a missing lower or upper bound stays open-ended. References retain their saved IDs even if their display names cannot be loaded.

Renaming a segment leaves its conditions unchanged. Empty groups and empty lists imported through the API are preserved and described in the editor; they are not silently removed. If a newer API introduces an unsupported condition, the editor preserves the complete definition and allows only name and description changes until the dashboard supports it.

Contact read permission allows inspection; contact write permission is required to create, edit, or delete. Saving recalculates membership in the background when the definition changes.

## Where segments are used

Segments are used to control AI behavior at runtime in two places:

### Actions

Every [action](/build-agents/actions) has a **Restricted to segments** list:

* **Empty list**: action is available to all contacts (default).
* **Non-empty list**: action is available only if the contact belongs to at least one listed segment.

A contact outside those segments cannot use or trigger that action. Anonymous contacts (no `contactId` yet) only get unrestricted actions.

### AI knowledge / training instructions

Every [AI instruction](/training/instructions) also has **Restricted to segments**, with the same behavior:

* **Empty list**: instruction applies to everyone.
* **Non-empty list**: instruction applies only to matching contacts.

### How the restriction is enforced

When a message arrives, OpenCX checks the contact's segment memberships and keeps only actions and instructions that apply to that contact.

Membership is precomputed in the background, so runtime checks stay fast.

## Use cases for segmentation

Beyond gating actions and instructions, segments are useful anywhere behavior should vary by cohort:

* **Workflow branching** — use the [Check Contact In Segment](/build-agents/workflows) action to read `isMember` and route a workflow down a different branch (e.g. send a different email template to *VIP* vs *Trial* contacts).
* **Outbound sequencing** — target a [sequence](/api-reference/sequences/index) at exactly the contacts in a segment instead of hand-curating a list.
* **Routing & SLAs** — close *VIP* sessions faster by attaching a stricter [SLA policy](/api-reference/sla/policies) when the contact belongs to the segment.
* **Reporting & analytics** — slice CSAT, handoff rate, or volume by segment to see how each cohort actually behaves.
* **Programmatic gating from your stack** — use [`check_contact_in_segment`](/api-reference/contacts/segments/check) from your backend or OpenCX MCP tools to gate features at the call site (for example, showing a different help-center widget per cohort).


# List contact segments
Source: https://docs.open.cx/api-reference/contacts/segments/list

get /contacts/segments
List contact segment definitions for the organization. Use when you need to discover what segments exist before checking membership or rendering a picker.



# List segments for a contact
Source: https://docs.open.cx/api-reference/contacts/segments/list-for-contact

get /contacts/segments/contacts/{contact_id}
List every segment a specific contact currently belongs to. A contact can be a member of multiple segments at once.



# Update a contact segment
Source: https://docs.open.cx/api-reference/contacts/segments/update

PATCH /contacts/segments/{segment_id}
Update a contact segment through the public API with segment write permission. Learn the request fields, responses, and membership behavior.

Requires `segments:write`.

Supply at least one of `name`, `description`, or `definition`. Omitted fields remain unchanged. A supplied definition replaces all filter rules; `null` matches all contacts. Filter changes recalculate membership in the background.

See [contact segment guidance](/api-reference/contacts/segments/introduction) for filter examples and membership timing.


# Set contact structured field values
Source: https://docs.open.cx/api-reference/contacts/set-structured-field-values

put /contacts/{contact_id}/structured-field-values
Set or clear Structured Field values on a contact. Use when your application records profile facts such as plan or tier on the contact, validated against the same fields sessions use.



# Update a contact
Source: https://docs.open.cx/api-reference/contacts/update

patch /contacts/{contact_id}
Update a contact. Use when your application needs to create, look up, or maintain the contact records that the AI agents converse with.



# Cancel active crawl
Source: https://docs.open.cx/api-reference/crawl/cancel-crawl

delete /crawl/{id}/crawl
Cancel the currently active crawl for the given website datasource. Use when driving the website crawler programmatically — queueing crawls, inspecting jobs, and curating indexed…



# Create a website datasource
Source: https://docs.open.cx/api-reference/crawl/create-datasource

post /crawl
Create a new website datasource and optionally start an initial crawl. Use when driving the website crawler programmatically — queueing crawls, inspecting jobs, and curating…



# Delete a website datasource
Source: https://docs.open.cx/api-reference/crawl/delete-datasource

delete /crawl/{id}
Delete a website datasource and all its crawl jobs and pages. Use when driving the website crawler programmatically — queueing crawls, inspecting jobs, and curating indexed pages.



# Exclude pages from sync
Source: https://docs.open.cx/api-reference/crawl/exclude-pages

post /crawl/{id}/pages/exclude
Exclude pages from sync — Bulk exclude pages from future syncs. Use when driving the website crawler programmatically — queueing crawls, inspecting jobs, and curating indexed…



# Get crawl job status
Source: https://docs.open.cx/api-reference/crawl/get-crawl-job

get /crawl/{id}/crawls/{jobId}
Retrieve the status and details of a specific crawl job. Use when driving the website crawler programmatically — queueing crawls, inspecting jobs, and curating indexed pages.



# Get website datasource details
Source: https://docs.open.cx/api-reference/crawl/get-datasource

get /crawl/{id}
Get website datasource details — Retrieve a website datasource with page statistics and active crawl job information.



# Include excluded pages back into sync
Source: https://docs.open.cx/api-reference/crawl/include-pages

post /crawl/{id}/pages/include
Bulk include previously excluded pages back into the sync cycle. Use when driving the website crawler programmatically — queueing crawls, inspecting jobs, and curating indexed…



# Crawl
Source: https://docs.open.cx/api-reference/crawl/index

The Crawl API allows you to programmatically crawl and index websites into your knowledge base.

The Crawl API allows you to programmatically crawl and index websites into your knowledge base.
This enables your AI agents to access and reference content from your website, documentation,
or any other web-based resources when responding to customer inquiries.

## Overview

Website crawling enables:

* **Automated Content Indexing** - Automatically extract and index content from websites
* **Knowledge Base Integration** - Crawled content is added directly to your knowledge base
* **Real-time Status Tracking** - Monitor crawl progress and completion status
* **Flexible Configuration** - Control include/exclude paths, page limits, and crawl intervals
* **Protected Sites** - Crawl sites behind HTTP Basic, bearer token, cookie, or custom-header authentication
* **Page Management** - Exclude, include, delete, or resync individual pages

## How It Works

1. **Create a Datasource** - Provide a website URL and configuration options
2. **Crawl Starts Automatically** - By default, a crawl begins immediately after creation
3. **Monitor Progress** - Check crawl status and track page processing
4. **Manage Pages** - Review crawled pages, exclude irrelevant ones, or resync outdated content
5. **Scheduled Recrawls** - Datasources automatically recrawl on a configurable interval

## Site Authentication

To crawl a site that isn't publicly accessible, set the optional `auth` field when creating
or updating a datasource. The credentials are sent to your site as request headers on every
crawl and are encrypted at rest — the API only ever returns `auth_configured` and
`auth_type`, never the secrets themselves.

* **`basic`** - HTTP Basic authentication (`username` + `password`)
* **`bearer`** - `Authorization: Bearer <token>`
* **`cookie`** - A raw `Cookie` header value (e.g. `session=…; token=…`)
* **`headers`** - Arbitrary custom headers (e.g. `X-Api-Key`)

On update, omit `auth` to leave it unchanged, pass `null` to clear it, or pass a new object
to replace it. The `User-Agent` header is reserved — crawls always identify as
`OpenCX-Crawler/1.0 (+https://open.cx)`.

## Crawl Job Statuses

* **`pending`** - Crawl job created, waiting to start
* **`scraping`** - Crawl is actively running and extracting content
* **`completed`** - Crawl finished successfully, content has been indexed
* **`failed`** - Crawl encountered an error and could not complete
* **`cancelled`** - Crawl was manually cancelled before completion

## Page Sync Statuses

* **`synced`** - Page content is indexed in the knowledge base
* **`pending`** - Page is waiting to be synced
* **`error`** - Page failed to sync
* **`excluded`** - Page is excluded from syncing

<Warning>
  Crawling large websites can take significant time and resources. Use include/exclude
  paths to focus on relevant content and set appropriate page limits.
</Warning>

## Available Endpoints

### Datasource Management

<CardGroup>
  <Card title="Create Datasource" icon="plus" href="./create-datasource">
    Create a new website datasource and start crawling
  </Card>

  <Card title="List Datasources" icon="list" href="./list-datasources">
    List all website datasources for your organization
  </Card>

  <Card title="Get Datasource" icon="eye" href="./get-datasource">
    Get datasource details with page stats
  </Card>

  <Card title="Update Datasource" icon="pen" href="./update-datasource">
    Update datasource configuration
  </Card>

  <Card title="Delete Datasource" icon="trash" href="./delete-datasource">
    Delete a website datasource
  </Card>
</CardGroup>

### Crawl Operations

<CardGroup>
  <Card title="Start Crawl" icon="play" href="./start-crawl">
    Start a new crawl for a datasource
  </Card>

  <Card title="Cancel Crawl" icon="stop" href="./cancel-crawl">
    Cancel an active crawl
  </Card>

  <Card title="List Crawl Jobs" icon="clock-rotate-left" href="./list-crawl-jobs">
    View crawl history for a datasource
  </Card>

  <Card title="Get Crawl Job" icon="magnifying-glass" href="./get-crawl-job">
    Check the status of a specific crawl job
  </Card>
</CardGroup>

### Page Management

<CardGroup>
  <Card title="List Pages" icon="file-lines" href="./list-pages">
    List crawled pages with filtering options
  </Card>

  <Card title="Exclude Pages" icon="eye-slash" href="./exclude-pages">
    Exclude pages from future syncs
  </Card>

  <Card title="Include Pages" icon="eye" href="./include-pages">
    Re-include previously excluded pages
  </Card>
</CardGroup>


# List crawl history
Source: https://docs.open.cx/api-reference/crawl/list-crawl-jobs

get /crawl/{id}/crawls
List crawl history — Retrieve a paginated list of crawl jobs for a website datasource.



# List website datasources
Source: https://docs.open.cx/api-reference/crawl/list-datasources

get /crawl
Retrieve a paginated list of all website datasources for your organization. Use when driving the website crawler programmatically — queueing crawls, inspecting jobs, and curating…



# List crawled pages
Source: https://docs.open.cx/api-reference/crawl/list-pages

get /crawl/{id}/pages
List crawled pages — Retrieve a paginated list of pages for a website datasource.



# Start a new crawl
Source: https://docs.open.cx/api-reference/crawl/start-crawl

post /crawl/{id}/crawl
Start a new crawl for the given website datasource. Use when driving the website crawler programmatically — queueing crawls, inspecting jobs, and curating indexed pages.



# Update website datasource settings
Source: https://docs.open.cx/api-reference/crawl/update-datasource

patch /crawl/{id}
Update configuration for a website datasource. Use when driving the website crawler programmatically — queueing crawls, inspecting jobs, and curating indexed pages.



# Check if CSAT is enabled for a channel
Source: https://docs.open.cx/api-reference/csat/check_channel

get /csat/settings/channel/{channel}
Check whether CSAT collection is enabled for the specified channel. Use when integrating CSAT results into a downstream BI or analytics pipeline.



# Check if CSAT has been sent for a session
Source: https://docs.open.cx/api-reference/csat/check_sent

get /csat/sessions/{session_id}/sent
Check whether a CSAT request has been sent for the specified session. Use when integrating CSAT results into a downstream BI or analytics pipeline.



# Get specific CSAT score
Source: https://docs.open.cx/api-reference/csat/get

get /csat/scores/{score_id}
Retrieve details of a specific CSAT score. Use when integrating CSAT results into a downstream BI or analytics pipeline.



# Get CSAT settings
Source: https://docs.open.cx/api-reference/csat/get-settings

get /csat/settings
Retrieve your CSAT settings — per-channel toggles plus the custom feedback-page and request-email template overrides.



# Get all CSAT scores
Source: https://docs.open.cx/api-reference/csat/get_all

get /csat/scores
Get all CSAT scores — Retrieve all CSAT scores for the organization with pagination



# Get session CSAT score
Source: https://docs.open.cx/api-reference/csat/get_session

get /csat/scores/session/{session_id}
Retrieve CSAT score for a specific session. Use when integrating CSAT results into a downstream BI or analytics pipeline.



# CSAT
Source: https://docs.open.cx/api-reference/csat/index

The CSAT (Customer Satisfaction) API allows you to programmatically manage customer satisfaction scores and settings within your organization.

The CSAT (Customer Satisfaction) API allows you to programmatically manage customer satisfaction scores and settings within your organization.
CSAT scores help you measure customer satisfaction and track the effectiveness of your customer support interactions.

<Tip>
  Looking for the setup guide? See [Collect Customer Satisfaction](/resources/csat) for how to enable CSAT, configure channels, and wire it into workflows.
</Tip>

## Overview

CSAT functionality in our system enables:

* **Customer Satisfaction Tracking** - Collect and analyze customer satisfaction scores for support interactions
* **Channel-Specific Settings** - Configure CSAT collection for different communication channels (web, phone, SMS, etc.)
* **Session Analytics** - Track CSAT scores per session and analyze customer satisfaction trends
* **Automated Collection** - Automatically send CSAT requests after support interactions
* **Performance Insights** - Monitor team performance and customer satisfaction metrics

## Available Endpoints

<CardGroup>
  <Card title="Get All CSAT Scores" icon="list" href="/api-reference/csat/get_all">
    Retrieve all CSAT scores with pagination
  </Card>

  <Card title="Get Specific CSAT Score" icon="magnifying-glass" href="/api-reference/csat/get">
    Get detailed information about a specific CSAT score
  </Card>

  <Card title="Get Session CSAT Score" icon="comments" href="/api-reference/csat/get_session">
    Retrieve CSAT score for a specific session
  </Card>

  <Card title="Check Channel Settings" icon="gear" href="/api-reference/csat/check_channel">
    Check if CSAT is enabled for a specific channel
  </Card>

  <Card title="Check CSAT Sent Status" icon="paper-plane" href="/api-reference/csat/check_sent">
    Check if CSAT has been sent for a session
  </Card>
</CardGroup>


# Update CSAT settings
Source: https://docs.open.cx/api-reference/csat/update-settings

patch /csat/settings
Update your CSAT settings — customize the feedback-page and request-email templates. Omitted keys are preserved; null clears a template back to the default design.



# Create a custom status
Source: https://docs.open.cx/api-reference/custom-statuses/create

post /custom-statuses
Define a new custom session status under one of the built-in statuses. Names are unique per organization.



# Delete a custom status
Source: https://docs.open.cx/api-reference/custom-statuses/delete

delete /custom-statuses/{id}
Remove a custom status. Sessions that carried it keep their built-in status and lose the custom one.



# Get a custom status
Source: https://docs.open.cx/api-reference/custom-statuses/get

get /custom-statuses/{id}
Fetch one custom session status by id, including its parent status and customer-facing display fields.



# Custom Statuses
Source: https://docs.open.cx/api-reference/custom-statuses/index

The Custom Statuses API lets you define the custom session statuses your team works with, and read or set the custom status on any session.

Every session has one of three built-in statuses: `open`, `closed_resolved`, or `closed_unresolved`. A custom status refines one of them with a name your team recognizes, such as "Waiting on customer" or "Escalated to engineering", plus an optional customer-facing label, color, and icon. This API manages those definitions and reads or sets the custom status on a session.

## Key Concepts

* **Custom status** — A named refinement of a built-in status. Each one has a `parent_status`; applying it to a session moves the session to that built-in status
* **`sub_status_id`** — Every session object carries the id of its custom status, or `null` when only the built-in status applies. Resolve ids with the list endpoint
* **Applying and clearing** — Set a session's custom status with `PUT /chat/sessions/{session_id}/sub-status`; clear it with `DELETE` on the same path. Clearing keeps the built-in status exactly as it is
* **Filtering** — `POST /chat/sessions/filter` accepts `sub_status_ids` to find sessions in any of the given custom statuses
* **Team access** — `allowed_group_ids` lists the teams whose agents may set the status from the inbox. An empty list allows every team. Deleting a team removes it from every list, so a status whose only allowed team is deleted becomes available to every team. Admins, API keys, and workflows can always set it, and a status already on a session stays visible to everyone
* **Customer-facing fields** — `display_name` and `display_description` are what customers may see; `name` and `description` are for your team only
* **Timeline** — Every set and clear leaves an event in the session history, attributed to the API

## Available Endpoints

<CardGroup>
  <Card title="List Custom Statuses" icon="list" href="./list">
    List every custom status in your organization
  </Card>

  <Card title="Get Custom Status" icon="eye" href="./get">
    Fetch one custom status by id
  </Card>

  <Card title="Create Custom Status" icon="plus" href="./create">
    Define a new custom status under a built-in one
  </Card>

  <Card title="Update Custom Status" icon="pen" href="./update">
    Change any subset of a custom status
  </Card>

  <Card title="Delete Custom Status" icon="trash" href="./delete">
    Remove a custom status
  </Card>

  <Card title="Set Session Custom Status" icon="circle-check" href="../chat-sessions/sub_status_set">
    Apply a custom status to a session
  </Card>

  <Card title="Clear Session Custom Status" icon="circle-xmark" href="../chat-sessions/sub_status_clear">
    Remove the custom status from a session
  </Card>
</CardGroup>


# List custom statuses
Source: https://docs.open.cx/api-reference/custom-statuses/list

get /custom-statuses
List every custom session status in your organization. Use it to resolve a session's sub_status_id to a name, or to pick an id before applying one.



# Update a custom status
Source: https://docs.open.cx/api-reference/custom-statuses/update

patch /custom-statuses/{id}
Change any subset of a custom status. Omitted fields stay as they are; send null to clear a display field, color, or icon.



# Assign insight to a group (team)
Source: https://docs.open.cx/api-reference/customer-insights/assign

post /insights/{id}/assign
Assign a customer insight to a specific group or team. Use when routing insights to the right owner or integrating with an external triage workflow.



# Get categories
Source: https://docs.open.cx/api-reference/customer-insights/categories/get

get /insights/categories
Retrieve the categories OpenCX uses to group customer-feedback insights. Use when driving the customer insights categorisation workflow from external code.



# Get one
Source: https://docs.open.cx/api-reference/customer-insights/get

get /insights/{id}
Get a specific customer insight — Retrieve detailed information about a specific insight



# Get customer insights
Source: https://docs.open.cx/api-reference/customer-insights/get_all

post /insights
Retrieve every customer insight the AI has surfaced, paginated. Use when driving the customer insights categorisation workflow from external code.



# Customer Insights
Source: https://docs.open.cx/api-reference/customer-insights/index

The Customer Insights API allows you to programmatically access and manage AI-generated insights from your customer interactions.

The Customer Insights API allows you to programmatically access and manage AI-generated insights from your customer interactions.
Our AI automatically analyzes every customer interaction across all channels (email, SMS, phone, WhatsApp, Slack, and web)
to extract meaningful patterns and insights that help you understand your customers better.

## Overview

Customer Insights are automatically generated from your customer interactions and consist of:

* **Pattern Recognition** - AI identifies recurring themes and issues
* **Sentiment Analysis** - Understanding customer satisfaction levels
* **Topic Clustering** - Grouping similar feedback and concerns
* **Cross-channel Intelligence** - Combining insights from all communication channels

## Available Endpoints

<CardGroup>
  <Card title="Get All Insights" icon="list" href="/api-reference/customer-insights/get_all">
    Retrieve all customer insights with optional filtering
  </Card>

  <Card title="Get Specific Insight" icon="magnifying-glass" href="/api-reference/customer-insights/get">
    Get detailed information about a specific insight
  </Card>

  <Card title="Resolve Insight" icon="check" href="/api-reference/customer-insights/resolve">
    Mark an insight as resolved
  </Card>

  <Card title="Assign Insight" icon="user-plus" href="/api-reference/customer-insights/assign">
    Assign an insight to a team member
  </Card>
</CardGroup>


# Mark an insight as resolved
Source: https://docs.open.cx/api-reference/customer-insights/resolve

post /insights/{id}/resolve
Mark an insight as resolved — Resolves a customer insight and optionally adds resolution details



# Delete a custom domain
Source: https://docs.open.cx/api-reference/email/delete_domains

delete /email/domains/{domainName}
Delete a custom domain from your organization. Use when managing email-channel provisioning — domain verification, unsubscribe handling, outbound email injection.



# Send emails
Source: https://docs.open.cx/api-reference/email/email_api

post /email
Send emails to multiple contacts, possibly with a time delay. Use when managing email-channel provisioning — domain verification, unsubscribe handling, outbound email injection.



# List all custom domains
Source: https://docs.open.cx/api-reference/email/get_domains

get /email/domains
List all custom domains for your organization, including their verification status and DNS records.

Each domain includes a nullable `region` field. New domains record `eu-west-1` (EU, Ireland) or `us-east-1` (US, North Virginia). Older domains may return `null` when their region has not been recorded; this does not change where they send email from.

See [Sending Domains & DNS](/email/sending-domains) for region selection and verification.


# Email Support
Source: https://docs.open.cx/api-reference/email/new

Open can handle support mail that you forward into the platform: conversations appear in the Open inbox, autopilot or agents can reply, and outbound mail is…

Open can handle support mail that you **forward** into the platform: conversations appear in the Open inbox, autopilot or agents can reply, and outbound mail is sent from your **registered** support address (after domain verification).

## Documentation (forwarding)

* **[Email introduction](/email/introduction)** — what the channel does, flow, integration surfaces, and handoff overview.
* **[Connect email forwarding](/email/forwarding)** — verify domain, register your address, forward to `forwarding@opencopilot.so`, complete the connection test.
* **[Email Flow](/email/forwarding-rules)** — routing, tokens, session matching, and outbound format.

## API reference (domains and sends)

For **programmatic** domain verification and **transactional** sends to contacts (separate from the forwarding inbox), use the **AI Email** endpoints in this section—for example [email API](/api-reference/email/email_api) and [domains](/api-reference/email/get_domains).

## Handoff

Same handoff model as other channels: see [Human handoff](/handoff/introduction).


# Start verification process for a custom domain
Source: https://docs.open.cx/api-reference/email/patch_domains_verify

patch /email/domains/{domainName}/verify
Start the verification process for a custom domain. Use when managing email-channel provisioning — domain verification, unsubscribe handling, outbound email injection.



# Add or update a custom domain for email sending
Source: https://docs.open.cx/api-reference/email/put_domains

put /email/domains
Add or update a custom domain for sending emails. Use when managing email-channel provisioning — domain verification, unsubscribe handling, outbound email injection.

Use the optional `region` field when adding a sending domain:

| Value | Sending region |
| - | - |
| `eu-west-1` | EU (Ireland), the default for new domains |
| `us-east-1` | US (North Virginia) |

```json theme={"dark"}
{
  "domainName": "support.example.com",
  "region": "eu-west-1"
}
```

The region cannot be changed after adding the domain. Adding an existing domain returns its existing configuration; it does not change the region.

See [Sending Domains & DNS](/email/sending-domains) for setup and verification.


# Unsubscribe Contacts
Source: https://docs.open.cx/api-reference/email/unsubscribe_api

Your contacts must be able to unsubscribe/opt out of receiving marketing emails.

Your contacts must be able to unsubscribe/opt out of receiving marketing emails.

You can set the `email_is_transactional` field when sending an email to specify its type. If a contact has unsubscribed, and the `email_is_transactional` attribute is set to `false`, the contact will *not* receive the email.

Open enables opting out contacts in two ways:

* An API for generating links that your contacts can click to unsubscribe
* An API for unsubscribing contacts from within your apps

## Unsubscribe Link

You can call [this endpoint](./unsubscribe_url_api) to generate a link that you can put in the body of any email, or anywhere in your application. You can generate this link using the contact's email, or their contact ID.

## Unsubscribe via API call from your apps

In case you want your contacts to unsubscribe in a way other than clicking a link and being redirected to Open, you can directly call [this endpoint](./unsubscribe_directly_api) to mark a contact as unsubscribed from all email.


# Directly Unsubscribe a Contact
Source: https://docs.open.cx/api-reference/email/unsubscribe_directly_api

POST https://api-v2.opencopilot.so/backend/email/{org_id}/unsubscribe/{contact_id}
Mark a contact as unsubscribed from outbound email. Use when enforcing an opt-out from an external unsubscribe workflow or suppression-list sync.

## Path Parameters

<ParamField type="string">
  Your copilot/organization ID.
</ParamField>

<ParamField type="string">
  The contact's ID.
</ParamField>

## Body

This endpoint does not accept a body.


# Get an Unsubscribe Link
Source: https://docs.open.cx/api-reference/email/unsubscribe_url_api

GET https://api-v2.opencopilot.so/backend/email/{org_id}/unsubscribe/url
Create a link that your contact can click to unsubscribe. This link will redirect your contact to Open.

## Path Parameters

<ParamField type="string">
  Your copilot/organization ID.
</ParamField>

## Query Parameters

<ParamField type="string">
  The contact's ID.
</ParamField>

<ParamField type="string">
  The contact's ID.
</ParamField>

<Note>
  You must provide either the `contactId` or the `contactEmail` query parameter. Otherwise, there is
  no way for Open to identify the contact.
</Note>


# Add user
Source: https://docs.open.cx/api-reference/groups/add_user

post /groups/{groupId}/users
Add user. Use when maintaining group membership and scoping from an external directory.



# Create
Source: https://docs.open.cx/api-reference/groups/create

post /groups
Create. Use when maintaining group membership and scoping from an external directory.



# Delete
Source: https://docs.open.cx/api-reference/groups/delete

delete /groups/{groupId}
Delete. Use when maintaining group membership and scoping from an external directory.



# Get
Source: https://docs.open.cx/api-reference/groups/get

get /groups/{groupId}
Get. Use when maintaining group membership and scoping from an external directory.



# Get all
Source: https://docs.open.cx/api-reference/groups/get_all

get /groups
Get all. Use when maintaining group membership and scoping from an external directory.



# Groups
Source: https://docs.open.cx/api-reference/groups/index

The Groups API allows you to programmatically manage user groups within your organization.

The Groups API allows you to programmatically manage user groups within your organization.
Groups are used to organize users, manage permissions, and automate task assignments, making it easier
to handle customer support and insights effectively.

## Overview

Groups in our system enable:

* **Permission Management** - Control access to features and data based on group membership
* **Support Hours & Team Assignment** - Define support schedules and automatically route customer inquiries to the right team
* **Automated Task Assignment** - Automatically assign customer insights and AI recommendations to specific teams
* **Team Organization** - Structure your support and operations teams efficiently

## Available Endpoints

<CardGroup>
  <Card title="Get Specific Group" icon="magnifying-glass" href="/api-reference/groups/get">
    Get detailed information about a specific group
  </Card>

  <Card title="Create Group" icon="plus" href="/api-reference/groups/create">
    Create a new group
  </Card>

  <Card title="Update Group" icon="pen" href="/api-reference/groups/update">
    Update an existing group
  </Card>

  <Card title="Delete Group" icon="trash" href="/api-reference/groups/delete">
    Delete a group
  </Card>

  <Card title="Get All Groups" icon="list" href="/api-reference/groups/get_all">
    Get all groups in the organization
  </Card>

  <Card title="Add User to Group" icon="user-plus" href="/api-reference/groups/add_user">
    Add a user to a group
  </Card>

  <Card title="Remove User from Group" icon="user-minus" href="/api-reference/groups/remove_user">
    Remove a user from a group
  </Card>
</CardGroup>


# Remove user
Source: https://docs.open.cx/api-reference/groups/remove_user

delete /groups/{groupId}/users/{userId}
Remove user. Use when maintaining group membership and scoping from an external directory.



# Update
Source: https://docs.open.cx/api-reference/groups/update

put /groups/{groupId}
Update. Use when maintaining group membership and scoping from an external directory.



# List handoff events
Source: https://docs.open.cx/api-reference/handoff-analytics/events

get /handoff-analytics/events
List handoff events — a paginated list of individual AI-to-human handoff events, each with the AI-written summary, explanation, handoff reasons, sentiment, and session ID.



# Get handoff analytics
Source: https://docs.open.cx/api-reference/handoff-analytics/get

get /handoff-analytics
Get handoff analytics — Get a comprehensive overview of AI-to-human handoff events for a date range, including reason breakdowns, sentiment analysis, trends, and referenced…



# Handoff Analytics
Source: https://docs.open.cx/api-reference/handoff-analytics/index

Handoff analytics provide visibility into why and when the AI agent hands conversations off to human agents.

Handoff analytics provide visibility into why and when the AI agent hands conversations off to human agents. Use this data to improve your AI's performance by identifying gaps in knowledge, tools, or instructions.

## What are Handoffs?

A handoff occurs when the AI agent determines it cannot fully resolve a customer's request and transfers the conversation to a human agent. Each handoff event captures:

* **Reason** — Why the AI handed off (missing knowledge, missing tools, unclear instructions, user request, prohibited topic)
* **Sentiment** — The customer's sentiment at the time of handoff
* **References** — What knowledge articles, tools, or instructions were involved

## Available Endpoints

<CardGroup>
  <Card title="Get Analytics" icon="chart-mixed" href="/api-reference/handoff-analytics/get">
    Get a comprehensive handoff analytics overview
  </Card>

  <Card title="List Events" icon="list" href="/api-reference/handoff-analytics/events">
    List individual handoff events with per-session reasons and summaries
  </Card>
</CardGroup>


# List the articles that link to a help center article
Source: https://docs.open.cx/api-reference/help-center/articles/backlinks

get /hc/{helpCenterId}/articles/{entityId}/backlinks
List the other articles that link to a help center article: the languages each one is live in with the link, and unsaved drafts that still carry it. Read it before deleting or unpublishing.



# Create a help center article
Source: https://docs.open.cx/api-reference/help-center/articles/create

post /hc/{helpCenterId}/articles
Create a help center article as a draft in the primary language under a category. Publish it separately to make it live and available to the AI.



# Delete a help center article
Source: https://docs.open.cx/api-reference/help-center/articles/delete

delete /hc/{helpCenterId}/articles/{entityId}
Permanently delete a help center article, its versions, and its entry in the AI index. Use unpublish instead to take it offline without losing it.



# Get a help center article
Source: https://docs.open.cx/api-reference/help-center/articles/get

get /hc/{helpCenterId}/articles/{entityId}
Fetch one help center article with its source version and every locale version. Use to read the current draft and published content.



# Get the per-language state of a help center article
Source: https://docs.open.cx/api-reference/help-center/articles/language_states

get /hc/{helpCenterId}/articles/{entityId}/language-states
Per language: whether the article is published, whether it has unpublished changes, and whether its translation is behind the source. Read it before publishing to know what will change.



# List help center articles
Source: https://docs.open.cx/api-reference/help-center/articles/list

get /hc/{helpCenterId}/articles
List every article in a help center with its locale for the requested language. Use to find article ids before updating or publishing.



# Publish a help center article (all locales)
Source: https://docs.open.cx/api-reference/help-center/articles/publish

post /hc/{helpCenterId}/articles/{entityId}/publish
Publish a help center article in every locale that has a version. This puts it on the public site and in the AI index in the same call.



# Publish one locale of a help center article
Source: https://docs.open.cx/api-reference/help-center/articles/publish_locale

post /hc/{helpCenterId}/articles/{entityId}/locales/{languageCode}/publish
Publish a single locale of a help center article. Use to ship the primary language now and release translations when they are reviewed.



# Restore a deleted help center article
Source: https://docs.open.cx/api-reference/help-center/articles/restore

post /hc/{helpCenterId}/articles/{entityId}/restore-deleted
Bring a deleted article back with its content and place it back in the tree. Only works while the article is still soft-deleted.



# Retranslate a help center article into one language
Source: https://docs.open.cx/api-reference/help-center/articles/retranslate

post /hc/{helpCenterId}/articles/{entityId}/retranslate
Regenerate the translation of a help center article for one language from its source version. Use after editing the source or the glossary.



# Retranslate a help center article into every enabled language
Source: https://docs.open.cx/api-reference/help-center/articles/retranslate_all

post /hc/{helpCenterId}/articles/{entityId}/retranslate-all
Regenerate the translations of a help center article for every enabled language. Use after a source edit that should reach all locales.



# Unpublish a help center article
Source: https://docs.open.cx/api-reference/help-center/articles/unpublish

post /hc/{helpCenterId}/articles/{entityId}/unpublish
Take a help center article off the public site for one locale or all of them. Unpublishing the primary locale also removes it from the AI.



# Update a help center article
Source: https://docs.open.cx/api-reference/help-center/articles/update

put /hc/{helpCenterId}/articles/{entityId}
Create a new draft version of a help center article with new title or content. Publish it afterwards to replace the live version.

The body is an HTML fragment in `content_html`; omit it to change only the title or search metadata and keep the existing body. Without `language_code` the update applies to the article's source language. Publishing is a separate call.


# List versions of a help center article
Source: https://docs.open.cx/api-reference/help-center/articles/versions

get /hc/{helpCenterId}/articles/{entityId}/versions
List the version history of a help center article for a language, with who saved and who published each version. Use to audit changes or pick a version id to publish as a rollback.



# Create a help center topic
Source: https://docs.open.cx/api-reference/help-center/categories/create

post /hc/{helpCenterId}/categories
Create a help center category in the primary language, optionally nested under a parent. Translations are generated in the background.



# Delete a help center topic
Source: https://docs.open.cx/api-reference/help-center/categories/delete

delete /hc/{helpCenterId}/categories/{categoryEntityId}
Delete a help center category. Its articles and subcategories are deleted with it unless move_contents_to names another category to re-home them under.



# Get a help center topic
Source: https://docs.open.cx/api-reference/help-center/categories/get

get /hc/{helpCenterId}/categories/{categoryEntityId}
Fetch one help center category with all of its locale versions. Use to read its name, description, icon, and parent before updating.



# List help center topics
Source: https://docs.open.cx/api-reference/help-center/categories/list

get /hc/{helpCenterId}/categories
List every category of a help center with its locale for the requested language. Top-level categories have a null parent id.



# Restore a deleted help center topic
Source: https://docs.open.cx/api-reference/help-center/categories/restore

post /hc/{helpCenterId}/categories/{categoryEntityId}/restore-deleted
Bring a deleted category back and place it back in the tree. Only works while the category is still soft-deleted.



# Retranslate a help center topic into one language
Source: https://docs.open.cx/api-reference/help-center/categories/retranslate

post /hc/{helpCenterId}/categories/{categoryEntityId}/retranslate
Regenerate the translation of a help center category for one language. Use after renaming it or changing its description in the source.



# Retranslate a help center topic into every enabled language
Source: https://docs.open.cx/api-reference/help-center/categories/retranslate_all

post /hc/{helpCenterId}/categories/{categoryEntityId}/retranslate-all
Regenerate the translations of a help center category for every enabled language after a change to its source name or description.



# Update a help center topic
Source: https://docs.open.cx/api-reference/help-center/categories/update

put /hc/{helpCenterId}/categories/{categoryEntityId}
Update the name, description, or icon of a help center category in one language. Writing the primary language retranslates the others; another language edits only that translation.



# Get a help center
Source: https://docs.open.cx/api-reference/help-center/get

get /hc/{id}
Read one help center: its name, description, domain, logo, languages, theme, custom CSS and head scripts, and per-language title and description overrides.



# Add a glossary term
Source: https://docs.open.cx/api-reference/help-center/glossary/create

post /hc/{id}/glossary
Add a term the translator must keep as defined. It applies to translations made from then on; existing translations are unchanged until retranslated.



# Delete a glossary term
Source: https://docs.open.cx/api-reference/help-center/glossary/delete

delete /hc/{id}/glossary/{termId}
Remove a glossary term. Later translations are free to render it however they like.



# Import glossary terms from the organization glossary
Source: https://docs.open.cx/api-reference/help-center/glossary/import

post /hc/{id}/glossary/import-from-translation
Copy the organization-wide translation glossary into this help center. Terms that already exist here are left alone.



# List the translation glossary
Source: https://docs.open.cx/api-reference/help-center/glossary/list

get /hc/{id}/glossary
List the translation glossary: terms the translator renders exactly as defined, such as product and feature names.



# Update a glossary term
Source: https://docs.open.cx/api-reference/help-center/glossary/update

put /hc/{id}/glossary/{termId}
Change a glossary term or its definition. It applies to translations made from then on; translations that already exist keep their wording until they are retranslated.



# Help Center API
Source: https://docs.open.cx/api-reference/help-center/index

Create, update, publish, and delete help center articles and categories from your own systems, and manage the site itself — languages, glossary, branding, and ordering.

The Help Center API lets you manage the customer-facing knowledge base you author in OpenCX from your own systems. Anything you can do in the [Help Center](/help-center/overview) editor you can do here: create and edit articles and categories, publish and unpublish them, manage translations and the glossary, order the tree, upload media, and change the site's own settings.

Publishing an article's primary language ships it to your public help site **and** the AI's knowledge in the same action. There is no separate "train the AI" step. Other languages publish to the site only; the AI always follows the primary language.

## Scopes

| Scope | Grants |
| - | - |
| `help-center-content:read` | List and fetch articles, categories, versions, the content tree, and media |
| `help-center-content:write` | Create, update, publish, unpublish, move, reorder, restore, delete, retranslate, upload |
| `help-center:read` | List and fetch help centers, their language settings, and their glossary |
| `help-center:write` | Change a help center's settings, served languages, and glossary |

`help-center:read` and `help-center:write` also grant the matching content scope, so an existing key keeps working unchanged. Create an API key under **Settings → API keys**. See [Authentication](/api-reference/authentication).

## Key concepts

* **Help center id** — every endpoint is scoped to one help center. Call [List help centers](./list) first to find the id.
* **Categories** — every article belongs to exactly one category. Categories can be nested; `parent_id` is `null` for top-level ones.
* **Source language** — each article records the language it was written in. Every other language is a translation of it. Pass `language_code` on [Create](./articles/create) when the article is authored in something other than the help center's primary language; it cannot be changed later.
* **Draft and published** — creating or updating an article writes a new **version**. Nothing is visible to customers or the AI until you call [Publish](./articles/publish), which ships the newest stored version. [Language states](./articles/language_states) tells you, per language, what is live and what is waiting.
* **Locales** — each enabled language has its own published state. [Publish](./articles/publish) releases every locale at once; [Publish one locale](./articles/publish_locale) lets you ship the primary language before translations are reviewed. Only the primary language feeds the AI: publishing a translation while the primary language is still unpublished makes that translation public without adding the article to the AI's knowledge.
* **Per-language structure** — where an article or category sits, and in what order, is recorded per language. A [move](./structure/move_article) changes one language's tree and leaves the others alone.
* **Unpublish, delete, restore** — [Unpublish](./articles/unpublish) takes an article offline while keeping its content and history; unpublishing the primary language also removes it from the AI's knowledge. [Delete](./articles/delete) is reversible through [Restore](./articles/restore) while the article is still soft-deleted.

<Note>
  Articles are either unpublished or published. There is no separate internal-only visibility today: an article published in its primary language is on the public site and in the AI's knowledge together. For content the AI should know but customers should not browse, use the [AI Training API](/api-reference/training/index) instead.
</Note>

## Available Endpoints

### Help centers

<CardGroup>
  <Card title="List help centers" icon="list" href="./list">
    Find the help center id
  </Card>

  <Card title="Get" icon="magnifying-glass" href="./get">
    Settings, branding, and custom code
  </Card>

  <Card title="Update" icon="pen" href="./update">
    Name, domain, CSS, head scripts
  </Card>
</CardGroup>

### Languages and glossary

<CardGroup>
  <Card title="Get languages" icon="language" href="./languages/get">
    Served languages and auto-translate
  </Card>

  <Card title="Update languages" icon="language" href="./languages/update">
    Change what is served
  </Card>

  <Card title="Translation jobs" icon="spinner" href="./translation_jobs">
    What is still translating
  </Card>

  <Card title="List terms" icon="list" href="./glossary/list">
    Terms the translator keeps
  </Card>

  <Card title="Add term" icon="plus" href="./glossary/create">
    Protect a product name
  </Card>

  <Card title="Update term" icon="pen" href="./glossary/update">
    Change a term or definition
  </Card>

  <Card title="Delete term" icon="trash" href="./glossary/delete">
    Remove a term
  </Card>

  <Card title="Import terms" icon="download" href="./glossary/import">
    Copy the organization glossary
  </Card>
</CardGroup>

### Articles

<CardGroup>
  <Card title="List" icon="list" href="./articles/list">
    All articles for a language
  </Card>

  <Card title="Get" icon="magnifying-glass" href="./articles/get">
    One article with its versions
  </Card>

  <Card title="Create" icon="plus" href="./articles/create">
    New article under a category
  </Card>

  <Card title="Update" icon="pen" href="./articles/update">
    New stored version
  </Card>

  <Card title="Publish" icon="rocket" href="./articles/publish">
    Go live in every locale
  </Card>

  <Card title="Publish one locale" icon="language" href="./articles/publish_locale">
    Go live in one language
  </Card>

  <Card title="Language states" icon="list-check" href="./articles/language_states">
    What is live, what is waiting
  </Card>

  <Card title="Unpublish" icon="eye-slash" href="./articles/unpublish">
    Take offline, keep content
  </Card>

  <Card title="Delete" icon="trash" href="./articles/delete">
    Remove from the tree
  </Card>

  <Card title="Restore" icon="rotate-left" href="./articles/restore">
    Bring a deleted article back
  </Card>

  <Card title="Versions" icon="clock-rotate-left" href="./articles/versions">
    Version history
  </Card>

  <Card title="Retranslate" icon="language" href="./articles/retranslate">
    One language or all
  </Card>
</CardGroup>

### Categories

<CardGroup>
  <Card title="List" icon="list" href="./categories/list">
    All categories for a language
  </Card>

  <Card title="Get" icon="magnifying-glass" href="./categories/get">
    One category with locales
  </Card>

  <Card title="Create" icon="plus" href="./categories/create">
    Top-level or nested
  </Card>

  <Card title="Update" icon="pen" href="./categories/update">
    Rename or re-icon, per language
  </Card>

  <Card title="Delete" icon="trash" href="./categories/delete">
    With or without its contents
  </Card>

  <Card title="Restore" icon="rotate-left" href="./categories/restore">
    Bring a deleted category back
  </Card>

  <Card title="Retranslate" icon="language" href="./categories/retranslate">
    One language or all
  </Card>
</CardGroup>

### Structure

<CardGroup>
  <Card title="Get tree" icon="folder-tree" href="./structure/tree">
    One language, whole tree, in order
  </Card>

  <Card title="Move article" icon="arrow-right-arrow-left" href="./structure/move_article">
    Into a category, at a position
  </Card>

  <Card title="Move category" icon="arrow-right-arrow-left" href="./structure/move_topic">
    Nest it or lift it to the top
  </Card>

  <Card title="Reorder" icon="sort" href="./structure/reorder">
    Order one category's children
  </Card>
</CardGroup>

### Media

<CardGroup>
  <Card title="Upload media" icon="upload" href="./media/upload">
    Images for article HTML
  </Card>

  <Card title="List media" icon="images" href="./media/list">
    Library contents and URLs
  </Card>

  <Card title="Delete media" icon="trash" href="./media/delete">
    Remove a file
  </Card>
</CardGroup>

## Best practices

* Create, review, then publish. An unpublished article never reaches customers or the AI.
* Article bodies are HTML fragments in `content_html`, on reads and writes. It replaces the former `content_markdown` field, which is no longer accepted.
* Read the article before you update it and send the whole `content_html` back — an update replaces the body rather than patching it.
* Read [Language states](./articles/language_states) before publishing so you know which locales the call will change.
* `enabled_languages` and `localizations` **replace** what is stored rather than merging. Read the current value first and send it back whole.
* Set a stable `slug` on create when you need permanent URLs; otherwise it is derived from the title.
* Upload images through [Upload media](./media/upload) and reference the returned URL in `content_html`.
* Embed a video with `<div data-embed="youtube" data-embed-id="aqz-KE-bpKQ"></div>`. `data-embed` is `youtube`, `vimeo`, `loom` or `wistia`; `data-embed-id` is the video's id from its link — for an unlisted Vimeo video, `76979871/8272103f6e`. An embed with another host or a malformed id is removed on save, and `<iframe>` is never kept.
* Unpublish rather than delete when content might come back.


# Get the languages a help center serves
Source: https://docs.open.cx/api-reference/help-center/languages/get

get /hc/{id}/languages
Read the source language every article is written in, the languages the site is served in, and whether translation runs automatically on publish.



# Change which languages a help center serves
Source: https://docs.open.cx/api-reference/help-center/languages/update

put /hc/{id}/languages
Set the languages a help center serves and whether publishing a source article translates it automatically. The list replaces what is stored; the primary language cannot be changed.



# List help centers
Source: https://docs.open.cx/api-reference/help-center/list

get /hc
List every help center this API key can access. Call it first to find the help center id used by every other Help Center endpoint.



# Delete help center media file
Source: https://docs.open.cx/api-reference/help-center/media/delete

delete /hc/{id}/media/{mediaId}
Delete a file from a help center media library. Articles that still embed its URL will show a broken image, so update them first.



# List help center media files
Source: https://docs.open.cx/api-reference/help-center/media/list

get /hc/{id}/media
List the files in a help center media library with their URLs. Use to find an existing asset to embed or a media id to delete.



# Upload media file to help center
Source: https://docs.open.cx/api-reference/help-center/media/upload

post /hc/{id}/media
Upload an image or file to a help center media library and get a permanent URL to embed in article content. Use before creating rich articles.



# Move an article to a topic
Source: https://docs.open.cx/api-reference/help-center/structure/move_article

post /hc/{helpCenterId}/structure/move-article
Place an article under a category at a position. By default the help center setting decides whether the other languages follow, appended at the end there; `scope` overrides it per call.



# Move a topic under another topic
Source: https://docs.open.cx/api-reference/help-center/structure/move_topic

post /hc/{helpCenterId}/structure/move-topic
Place a category under another one, or at the top level, at a position. The help center setting decides whether other languages follow; `scope` overrides it. Nesting under itself is rejected.



# Reorder the children of one topic
Source: https://docs.open.cx/api-reference/help-center/structure/reorder

post /hc/{helpCenterId}/structure/reorder
Set the order of everything directly under one category — subcategories and articles alike — in one language.



# Get the help center content tree
Source: https://docs.open.cx/api-reference/help-center/structure/tree

get /hc/{helpCenterId}/structure/tree
The whole content tree for one language: nested categories with their articles, in the order they are served, each article flagged with its version and publish state.



# List translations still running
Source: https://docs.open.cx/api-reference/help-center/translation_jobs

get /hc/{id}/translation-jobs
Translations that have not finished yet, with the language and the article or category each one is for. Poll it after a publish or a retranslate to know when the other languages have caught up.



# Update a help center
Source: https://docs.open.cx/api-reference/help-center/update

put /hc/{id}
Change a help center: name, description, domain, logo, custom CSS, custom head scripts, sidebar layout, translation prompt, and per-language title and description overrides.



# Create a saved inbox view
Source: https://docs.open.cx/api-reference/inbox-views/create

post /inbox-views
Save a named, filtered view of the inbox and share it with the organization, named teams, or named users.

Use `group_by: "tags"` to group by tags. For `contact_attribute` or
`session_attribute`, also set `group_by_attribute` to the exact key. Grouping
applies to loaded sessions in the inbox. See [grouping saved views](./index#grouping).


# Delete a saved inbox view
Source: https://docs.open.cx/api-reference/inbox-views/delete

delete /inbox-views/{id}
Remove a saved view. It disappears from the sidebar for everyone it was shared with; the sessions it matched are untouched.



# Inbox Views
Source: https://docs.open.cx/api-reference/inbox-views/index

The Inbox Views API lets you create, update, and share the saved views your agents pick from the inbox sidebar — a named filter set that stays live every time it is opened.

A saved view is a named session filter set that appears in the inbox sidebar. Agents pick one to work a queue — "Phone — needs a human", "Assigned to me today", "Escalations". This API creates those views, updates them, and decides who sees them, so a view can ship alongside the workflow that populates it instead of being rebuilt by hand.

## Key Concepts

* **Filters** — The same vocabulary as `POST /chat/sessions/filter`, ANDed together. A view with no filters covers every session
* **Live evaluation** — A view is re-run every time it is opened, so two filters only saved views have are worth knowing: the `$current_user` assignee token resolves to whoever opens the view, and `date.preset` (`today`, `last_3_days`, `last_7_days`) is a rolling window, not the day the view was saved
* **Sharing** — Leave both share lists empty for an organization-wide view; name users and/or teams to restrict it; pass only your own user id to keep it private. The `visibility` field reports which of the three applies
* **Permissions** — Anyone who can write sessions can save a view for themselves. Sharing one with other people needs the shared-views permission; without it a created view is silently locked to its creator. `can_edit` and `can_delete` on every view say what the caller may do to it
* **Advanced views** — A view built in the dashboard with OR groups or excluded clauses reads back with `advanced: true` and `filters: null`, because this API models a single set of ANDed filters. Its sort and grouping are still editable; sending `filters` replaces the whole saved query

## Grouping

Set `group_by` to `tags`, `contact_attribute`, or `session_attribute` to use the
additional inbox grouping options. Attribute grouping also uses
`group_by_attribute`, the exact attribute key:

```json theme={"dark"}
{
  "name": "Sessions by plan",
  "group_by": "contact_attribute",
  "group_by_attribute": "plan"
}
```

The dashboard groups only the sessions it has loaded. Tags can place one session
in several groups. Contact grouping uses verified contact attributes. Session
grouping uses stored session attributes, falling back to editable attributes only
when the key is absent. Missing attribute values appear under **Not set** at the
bottom. See [group sessions](/inbox/intro#group-sessions) for value types and list
behavior.

On update, omitting grouping fields preserves them. Changing `group_by` clears
the previous attribute key unless a replacement `group_by_attribute` is supplied.
Setting `group_by_attribute` to `null` clears the key; attribute grouping with no
key renders a flat list. Setting `group_by` to `null` removes grouping.

## Available Endpoints

<CardGroup>
  <Card title="List Inbox Views" icon="list" href="./list">
    List the saved views the caller can see
  </Card>

  <Card title="Create Inbox View" icon="plus" href="./create">
    Save a new filtered view and share it
  </Card>

  <Card title="Update Inbox View" icon="pen" href="./update">
    Change a view's name, filters, sorting, or sharing
  </Card>

  <Card title="Delete Inbox View" icon="trash" href="./delete">
    Remove a saved view
  </Card>

  <Card title="Filter Chat Sessions" icon="magnifying-glass" href="../chat-sessions/filter">
    Run the same filters as a one-off search
  </Card>
</CardGroup>

Views also support `sort_by: "snoozed_until"` to order by the scheduled return time.
Snooze filters created in the dashboard are advanced filters and read back with
`advanced: true` and `filters: null`. This sorting option does not snooze a session. See [session snoozing](/inbox/intro#snooze-a-session) for inbox usage.


# List saved inbox views
Source: https://docs.open.cx/api-reference/inbox-views/list

get /inbox-views
List the saved inbox views the caller can see — their own, the ones shared with them or their teams, and the organization-wide ones.



# Update a saved inbox view
Source: https://docs.open.cx/api-reference/inbox-views/update

patch /inbox-views/{id}
Change any subset of a saved view. Omitted fields are left unchanged; sending filters replaces the view's whole saved query.

Use `group_by_attribute` to change an attribute grouping's key. Omit it to keep
the current key when the grouping field stays the same, or send `null` to clear
it. Changing `group_by` clears the old key unless you supply a new one. See
[grouping saved views](./index#grouping).


# Media
Source: https://docs.open.cx/api-reference/media/index

The Media API allows you to upload image files to OpenCX storage. Uploaded images return a permanent URL that can be embedded in training scenario content, help center articles, and other rich-text…

The Media API allows you to upload image files to OpenCX storage. Uploaded images return a permanent URL that can be embedded in training scenario content, help center articles, and other rich-text fields.

## Constraints

* **Allowed formats:** PNG, JPEG, GIF, WebP
* **Max file size:** 5 MB
* **Magic bytes validation:** file content must match the declared MIME type
* **Scope required:** `media:write`

## Available Endpoints

<CardGroup>
  <Card title="Upload Image" icon="upload" href="./upload">
    Upload an image and get a URL
  </Card>
</CardGroup>


# Upload an image
Source: https://docs.open.cx/api-reference/media/upload

post /media/upload
Upload an image to your organization storage. Use when uploading attachments to be referenced by other OpenCX resources.



# Create an office hours schedule
Source: https://docs.open.cx/api-reference/office-hours/create

post /office-hours
Create a new office hours schedule with time shifts. Use when provisioning business-hours coverage schedules programmatically.

## Holidays and exceptions

Use `exceptions` to configure named holidays, closures and extra opening periods. Dates use the schedule timezone. On update, omit the array to preserve existing exceptions, or send `[]` to clear them. See [Office hours and holidays](/api-reference/office-hours/index) for precedence, recurrence and examples.


# Delete an office hours schedule
Source: https://docs.open.cx/api-reference/office-hours/delete

delete /office-hours/{id}
Delete an office hours schedule and all its shifts. Use when provisioning business-hours coverage schedules programmatically.



# Get an office hours schedule
Source: https://docs.open.cx/api-reference/office-hours/get

get /office-hours/{id}
Get a specific office hours schedule by ID, including all its shifts. Use when provisioning business-hours coverage schedules programmatically.



# Get default office hours
Source: https://docs.open.cx/api-reference/office-hours/get-default

get /office-hours/default
Get the organization-wide default office hours schedule. Use when reading the fallback business-hours coverage that applies when a conversation has no team-specific schedule.



# Office hours and holidays
Source: https://docs.open.cx/api-reference/office-hours/index

Configure weekly availability, dated closures and recurring holidays in one place, then use the same schedules for teams and workflow routing.

Office Hours stores weekly availability and calendar exceptions for your organization. Use named schedules for individual teams, countries or workflow branches, and the default schedule for organization-wide availability.

## Configure in the dashboard

Open **Settings → Office Hours**. You need permission to read these settings; editing requires **Office Hours: Write**.

1. Edit the default schedule or add/edit a custom schedule.
2. Select its timezone and weekly shifts. No weekly shifts means open 24/7, except during closures and holidays.
3. Under **Holidays and exceptions**, choose **Add holiday or exception**.
4. Enter a name, type, start and end. Dates and times use the schedule's timezone, not your browser's timezone. The end is exclusive: Christmas Day starts at December 25 midnight and ends at December 26 midnight.
5. Enable **Repeat every year** for a fixed annual date. Leave it off for a one-off holiday or a holiday whose date changes each year.
6. Save the schedule. Repeat for each calendar exception.

Exception types:

| Type | Effect |
| - | - |
| Holiday (closed) | Closes the schedule and identifies the closure as a holiday for workflow routing. |
| Closed | Closes the schedule for the specified period. |
| Extra opening hours | Opens the schedule outside its normal weekly shifts. |

When exceptions overlap, **Holiday → Closed → Extra opening hours → weekly shifts** determines availability. Extra opening hours do not reopen a holiday. To shorten a working day, add a closure covering the hours you want to remove. Existing weekly shifts resume outside the exception period.

A yearly exception starts repeating from its configured year and must span less than a year. Periods can cross December into January. An occurrence with an invalid date, such as February 29 in a non-leap year, is skipped. Moving holidays must be entered with their actual dates each year; there is no automatic national-holiday feed. Each schedule supports up to 200 exceptions.

Configured start and end times skipped by a daylight-saving clock change are rejected. If a later yearly occurrence falls in a skipped hour, that boundary moves to the first valid local time after the gap. When clocks repeat a local time, the earlier occurrence is used. Check recurring exceptions that fall near clock changes when updating your calendar.

Campaign weekly send windows still follow the recipient's timezone when it is available. Holidays and other dated exceptions always follow the schedule's timezone.

Updating a named calendar refreshes its upcoming SLA transitions and active deadlines. Closed time does not consume the remaining SLA budget. If a calendar has no future opening, affected timers remain frozen until you reopen the calendar. Existing snoozes and paused resolution timers remain paused.

## Use schedules in workflows and IVRs

Use **Get Custom Working Hours** with the named schedule, or **Get Default Working Hours** for the organization default. Both use the current schedule configuration and return:

* `isNowWithinHours` (custom) or `isNowWithinDefaultWorkingHours` (default): whether the schedule is open, including its exceptions.
* `isHoliday`: whether a holiday exception is active.
* `exceptionName`: the active exception's name, or an empty string.
* `secondsUntilNextOpen`: seconds until the next opening; zero when already open. If no next opening can be calculated, this is a **3,600-second recheck interval**, not a promised opening.
* `nextOpeningKnown`: false when the schedule is closed with no known opening.

For a workflow that must wait for office hours, branch on the open status first. When closed, wait the returned seconds, then run the Office Hours check again. Only proceed when `isNowWithinHours` (custom schedule) or `isNowWithinDefaultWorkingHours` (default schedule) is true. A Wait step alone does not guarantee the schedule is open, including when a closure changes while the run is waiting.

Sequences that respect Office Hours remain held when a valid calendar has no opening. They recheck hourly and release the held sends once the calendar permits them, including after you edit the schedule.

For separate IVR branches, check `isHoliday` first, then `isNowWithinHours`; use the remaining branch for ordinary closures. Keep dates and time calculations in Office Hours rather than copying them into workflow code. A named schedule must be explicitly selected by the workflow; creating it alone does not change routing.

If two branches use different hours, create two named schedules and check the appropriate one in each branch. Existing workflows with embedded calendars continue using those calendars until updated to use the Office Hours actions.

## API and MCP

Reading requires `office-hours:read`; creating or updating requires `office-hours:write`. The existing create and update operations accept an optional `exceptions` array:

```json theme={"dark"}
{
  "name": "France Support",
  "iana_timezone": "Europe/Paris",
  "shifts": [
    { "day_of_week": "monday_to_friday", "start_time": "09:00:00", "end_time": "17:00:00" }
  ],
  "exceptions": [
    {
      "name": "Christmas Day",
      "kind": "holiday",
      "starts_at": "2026-12-25T00:00:00",
      "ends_at": "2026-12-26T00:00:00",
      "repeat_yearly": true
    }
  ]
}
```

This is a create request. Custom-schedule updates also require each existing shift's `id`. Default-schedule requests omit `name`, and default shifts omit `id`.

On update, **omitting `exceptions` preserves them**, supplying an array replaces them, and supplying `[]` clears them. Include every exception you want to retain when replacing the array. Existing clients that update only weekly shifts will not erase holidays. Local timestamps must include seconds and must not include `Z` or a timezone offset.

MCP exposes the same field on `create_office_hours`, `update_office_hours` and `update_default_office_hours`. Read back the schedule after saving to confirm its dates and timezone.

<CardGroup>
  <Card title="Get Default" icon="clock" href="./get-default">Read the organization-wide fallback schedule.</Card>
  <Card title="Update Default" icon="pen-to-square" href="./update-default">Save default shifts and exceptions.</Card>
  <Card title="List Schedules" icon="list" href="./list">List named schedules.</Card>
  <Card title="Get Schedule" icon="magnifying-glass" href="./get">Read a named schedule.</Card>
  <Card title="Create Schedule" icon="plus" href="./create">Create shifts and exceptions together.</Card>
  <Card title="Update Schedule" icon="pen" href="./update">Replace shifts or exceptions.</Card>
  <Card title="Delete Schedule" icon="trash" href="./delete">Delete a named schedule.</Card>
</CardGroup>


# List office hours schedules
Source: https://docs.open.cx/api-reference/office-hours/list

get /office-hours
List all office hours schedules for your organization. Use when provisioning business-hours coverage schedules programmatically.



# Update an office hours schedule
Source: https://docs.open.cx/api-reference/office-hours/update

put /office-hours/{id}
Update an office hours schedule. Use when provisioning business-hours coverage schedules programmatically.

## Holidays and exceptions

Use `exceptions` to configure named holidays, closures and extra opening periods. Dates use the schedule timezone. On update, omit the array to preserve existing exceptions, or send `[]` to clear them. See [Office hours and holidays](/api-reference/office-hours/index) for precedence, recurrence and examples.


# Update default office hours
Source: https://docs.open.cx/api-reference/office-hours/update-default

put /office-hours/default
Set or replace the organization-wide default office hours. Use when configuring the fallback business-hours coverage that applies when a conversation has no team-specific schedule.

## Holidays and exceptions

Use `exceptions` to configure named holidays, closures and extra opening periods. Dates use the schedule timezone. On update, omit the array to preserve existing exceptions, or send `[]` to clear them. See [Office hours and holidays](/api-reference/office-hours/index) for precedence, recurrence and examples.


# Get current organization
Source: https://docs.open.cx/api-reference/organization/get

get /org
Get current organization — Retrieve the organization associated with the current API key.



# Organization
Source: https://docs.open.cx/api-reference/organization/index

The Organization API allows you to programmatically retrieve and update your organization''s settings via the public API.

The Organization API allows you to programmatically retrieve and update your organization's settings via the public API.

## Overview

Your API key is scoped to a single organization. Use these endpoints to:

* **Retrieve settings** — Get current organization details like name, language, website, and AI prompt
* **Update settings** — Modify your organization's configuration without accessing the dashboard

## Authentication

All endpoints require a valid API key passed as a Bearer token in the `Authorization` header.

The organization is automatically inferred from the API key — you never need to pass an org ID.

## Available Endpoints

<CardGroup>
  <Card title="Get Organization" icon="eye" href="/api-reference/organization/get">
    Retrieve the current organization's details
  </Card>

  <Card title="Update Organization" icon="pen" href="/api-reference/organization/update">
    Update the current organization's settings
  </Card>
</CardGroup>


# Update current organization
Source: https://docs.open.cx/api-reference/organization/update

patch /org
Update settings of the organization associated with the current API key. Use when syncing organisation-level settings programmatically.



# Block an address from outbound contact
Source: https://docs.open.cx/api-reference/outbound-blocklist/block

post /outbound/blocklist
Add a phone number, email address or WhatsApp user id to the do-not-contact list, optionally until a date. Idempotent and only ever strengthens an existing block.



# Check whether an address is blocked
Source: https://docs.open.cx/api-reference/outbound-blocklist/check

get /outbound/blocklist/check
Tell whether an address is currently on the do-not-contact list and on which channels, ignoring expired entries. Use before pushing a lead into a sequence.



# Outbound Blocklist API
Source: https://docs.open.cx/api-reference/outbound-blocklist/index

Manage the do-not-contact list that stops sequences from reaching an address on any channel. Use to honour opt-outs from your own systems and to sync consent.

The outbound blocklist is the organization's **do-not-contact list**. An address on it is never contacted by a sequence: the engine checks the list when people are enrolled, when a sequence launches, and again before every single send. If the list cannot be read, the send is held rather than released.

<Note>
  This is not the [Blocklist API](/api-reference/blocklist/index). That one is **inbound**: it stops the AI from replying to a visitor who messages you. This one is **outbound**: it stops you reaching out. They answer different questions and share no storage.
</Note>

## What an entry is

Entries are keyed on the **address**, not on a contact record, so consent survives the contact being merged, deleted or re-imported.

| Field | Meaning |
| - | - |
| `identity_type` | `phone`, `email` or `whatsapp_user_id`. |
| `identity_value` | The address as stored after normalization: phone numbers in international format, emails lowercased. |
| `channel` | Which channel the entry covers. `null` means every channel; entries added through this API are always `null`. A specific channel appears when the person opted out of that channel alone. |
| `reason` | Why the address was blocked. Free text for your own auditing on entries you add. |
| `source` | Where the entry came from. `api` is one you added. Anything else was recorded when the person opted out themselves, or when their address bounced. |
| `expires_at` | When the block lifts automatically. `null` means never. |

### Who else writes entries

The list is shared with the channels themselves. Besides what you add, entries appear when:

* a person opts out of WhatsApp marketing messages (`channel: whatsapp`),
* a person unsubscribes from an email through the unsubscribe link or one-click header (`channel: email`),
* an email address hard-bounces (`channel: email`).

Those entries carry a `source` other than `api`. [List](/api-reference/outbound-blocklist/list) returns all of them so a sync into your CRM sees everything.

## How channels are covered

A block applies to every channel that could reach the address:

| Blocked identity | Stops |
| - | - |
| `phone` | WhatsApp messages and phone calls to that number. |
| `whatsapp_user_id` | WhatsApp messages to that account. Says nothing about calls or email. |
| `email` | Email to that address. Says nothing about WhatsApp or calls. |

Someone reachable on WhatsApp without a known phone number is a separate identity: if you hold both a phone and a WhatsApp user id for a person, block both.

A person is skipped at enrollment only when every channel they could be reached on is blocked. A block on one channel leaves them enrollable, and the launch and send gates hold them on that channel only.

## Rules

* **Blocking is idempotent and only strengthens.** Re-blocking an existing address never shortens its expiry and never turns a permanent block into a temporary one. Retrying a queued job is harmless.
* **`expires_at` must be in the future.** Omit it for a permanent block.
* **Unblocking defaults to your own entries.** [Unblock](/api-reference/outbound-blocklist/unblock) removes entries with `source: api` that cover every channel. A person's own opt-out and single-channel entries are left in place and counted in `skipped`. When `skipped` is above zero the address is still blocked; pass `include_provider_entries=true` to remove those too, deliberately.
* **Check ignores expired entries.** [Check](/api-reference/outbound-blocklist/check) answers `blocked` when at least one live entry exists and returns them, so you can see which channel each covers.
* **Invalid addresses are rejected**, never stored as-is, so junk can never occupy an address's slot.

## Scopes

Entries govern outbound sending, so the endpoints use the sequence scopes: `sequences:write` to block and unblock, `sequences:read` to check and list.

## Available endpoints

<CardGroup>
  <Card title="Block address" icon="user-slash" href="/api-reference/outbound-blocklist/block">Add a phone, email or WhatsApp user id</Card>
  <Card title="Unblock address" icon="user-check" href="/api-reference/outbound-blocklist/unblock">Remove an address, with skipped reporting</Card>
  <Card title="Check address" icon="magnifying-glass" href="/api-reference/outbound-blocklist/check">Is this address blocked, and on which channels</Card>
  <Card title="List addresses" icon="list" href="/api-reference/outbound-blocklist/list">Page through the whole list, newest first</Card>
</CardGroup>


# List blocked addresses
Source: https://docs.open.cx/api-reference/outbound-blocklist/list

get /outbound/blocklist
Page through the do-not-contact list, newest first, including entries people created by opting out themselves. Filter by identity type to sync into your CRM.



# Unblock an address
Source: https://docs.open.cx/api-reference/outbound-blocklist/unblock

delete /outbound/blocklist
Remove an address from the do-not-contact list. By default only entries added through the API are removed; a person’s own opt-out is reported as skipped.



# Start a connected app voice call
Source: https://docs.open.cx/api-reference/phone/connect_web_call

post /phone/web-calls/{callId}/connect
Connect app voice call through the Voice SDK integration. Use with the authentication and customer identity flow described in the app voice guide.

See [Voice SDK integration](/phone/voice-sdk) for authentication, platform packages, routing, and preview availability.

The SDK calls this after joining and publishing microphone audio. Use `Authorization: Bearer <controlToken>` from call creation. Only this OpenCX call token is accepted for call control; permanent API keys are not accepted. Use the SDK to manage the audio connection before activation.

Returns HTTP 200 with `{ "success": true }`. Repeated activation of an active call is safe. Expired or ended calls, missing microphone publication, and unavailable support return 409. A failed activation ends its reserved call; begin a new call attempt with a new request ID.


# Create an AI phone agent
Source: https://docs.open.cx/api-reference/phone/create

post /phone
Create an AI phone agent powered by the latest voice model. Use when orchestrating voice calls programmatically — placing outbound calls or listing call history.



# Create an app voice call
Source: https://docs.open.cx/api-reference/phone/create_web_call

post /phone/web-calls
Create app voice call through the Voice SDK integration. Use with the authentication and customer identity flow described in the app voice guide.

See [Voice SDK integration](/phone/voice-sdk) for authentication, platform packages, routing, and preview availability.

Enable **Allow calls from apps** in **Settings → Voice & Telephony** for this organization. Disabling it blocks new calls and activation of pending calls; active calls can finish.

Call this endpoint from your authenticated server with a `phone:write` API key. Resolve `contactId` from the signed-in customer and choose an authorized `destination`: either `{ type: 'agent', id }` or `{ type: 'team', id }`.

Reuse the UUID `requestId` for identical retries until activation. Changed settings or retries after activation return 409. `maxDurationSeconds` defaults to 1800 and accepts integers from 60 to 3600; the duration starts at activation.

A successful response is HTTP 200 with `callId`, `sessionId`, `controlToken`, and `expiresAt`. Pass this object unchanged to the OpenCX SDK; it manages the audio connection internally. Audio connection URLs and participant credentials are not part of this response. Join and activate within two minutes. `expiresAt` is the outer call-control deadline, not an extension of that join window. Credentials must be returned only to the authenticated customer and must not be logged or cached.

Creation returns 400 for invalid settings or unsupported agent transfers, 401 for invalid authentication, 403 for missing scope, disabled app calling, or a blocked contact, 404 for an unavailable contact/destination, 409 for conflicting or active calls, and 429 when requests are throttled.


# End an app voice call
Source: https://docs.open.cx/api-reference/phone/end_web_call

delete /phone/web-calls/{callId}
End app voice call through the Voice SDK integration. Use with the authentication and customer identity flow described in the app voice guide.

See [Voice SDK integration](/phone/voice-sdk) for authentication, platform packages, routing, and preview availability.

Use `Authorization: Bearer <controlToken>` for this exact call. Returns HTTP 200 with `{ "success": true }`. Ending a call disconnects all its participants and settles its call history. Repeated requests are safe while the control token remains valid.

If the request fails, the SDK still stops local audio. Server cleanup handles abandoned calls independently. Invalid, expired, or mismatched control tokens return 401.


# Finish your wrap-up for a closed phone session
Source: https://docs.open.cx/api-reference/phone/finish_wrap_up

post /agent-availability/me/wrap-up/ready
End your wrap-up for a closed phone session from an approved mini app. Use after saving a wrap-up code and confirming that the session is closed.

This action ends the authenticated teammate’s wrap-up only when it belongs to the supplied **closed phone session**. It does not close the session, save a code, hang up a call, or turn an unavailable agent online.

An approved mini app can save the wrap-up code, close the session through [Update a session](/api-reference/chat-sessions/update), confirm that closure succeeded, and then call `finishSessionWrapUp` with the same `session_id`. If closure fails, keep the wrap-up active and let the teammate retry.

* Requires `agent-availability:write` and a token bound to the acting teammate. A plain organization API key has no teammate identity and returns `403`.
* `cleared: true` means the matching wrap-up was cleared and the dashboard was notified.
* `cleared: false` means no matching wrap-up was cleared: it may already have finished, belong to another session, or the supplied session may still be open. Do not interpret this as proof that the agent is available.
* Repeated requests are safe. The call’s wrap-up identity is retained so a delayed call-end event does not reopen the same wrap-up window.

New calls still require the teammate’s normal availability, team eligibility, and calling connection. The existing **I’m ready** button continues to work independently.


# Get app voice call status
Source: https://docs.open.cx/api-reference/phone/get_web_call

get /phone/web-calls/{callId}
Get app voice call through the Voice SDK integration. Use with the authentication and customer identity flow described in the app voice guide.

See [Voice SDK integration](/phone/voice-sdk) for authentication, platform packages, routing, and preview availability.

Use `Authorization: Bearer <controlToken>` for this exact call. Returns HTTP 200 with `state`: `waiting`, `queued`, `connected`, or `ended`. The SDK polls this endpoint automatically.

`connected` requires an observed ready support participant. A queued offer or acceptance without a joined participant is not reported as connected. Invalid, expired, or mismatched control tokens return 401.


# Hand back a transferred call
Source: https://docs.open.cx/api-reference/phone/hand_back_call

post /phone/calls/hand-back
Return a caller that a Classical IVR transferred to your SIP endpoint, so the flow can route them to a team. Use when your system is done with the call.

When a Classical IVR transfers a caller to a SIP destination, the caller stays on the OpenCX call while your SIP endpoint talks to them. Call this endpoint, instead of hanging up, when the caller should continue with the organization. OpenCX hangs up your SIP leg, then the IVR continues with the steps after the transfer, usually a transfer to a team. The caller keeps the same call, recording and session throughout.

Send the session ID you received in the `X-OPENCX-SESSION-ID` SIP header of the transfer. The destination must list `X-OPENCX-SESSION-ID` among its allowed headers if it uses an allowlist.

* Create the API key with the **Hand back transferred calls** (`phone-calls:write`) scope. That scope cannot read or change any other phone configuration. A `phone:write` key can also hand calls back.
* Pass an optional `summary` of the conversation so far. It replaces the session's summary before the teammate is connected, so they see it when the call rings. It is saved only when the hand-back is accepted.
* Repeating a successful hand-back returns the same response and changes nothing; a `summary` sent with the repeat is ignored.
* A `409` means the session has no transferred call waiting: your leg has not answered yet, your leg or the caller already hung up, or the session has no SIP transfer. Hanging up without calling this endpoint returns the caller to the IVR, which continues with the `completed` outcome.
* A `404` means the session does not exist in the organization that owns the API key.

Do not hang up your leg first: OpenCX hangs it up for you once the hand-back is accepted. If your leg hangs up before the hand-back arrives, the hand-back is still accepted for a few seconds.


# List AI phone agents
Source: https://docs.open.cx/api-reference/phone/list

get /phone
List all AI phone agents in your organization with full details including name, type, model, voice, language, phone number, and configuration.



# List transfer destinations
Source: https://docs.open.cx/api-reference/phone/list_transfer_destinations

get /phone/transfer-destinations
List the transfer destinations configured for your organization. Reference their IDs in transfer_destination_ids when creating or updating a phone agent so it can transfer calls to them.



# Make an AI phone call
Source: https://docs.open.cx/api-reference/phone/make_outbound_call

post /phone/outbound-call
Request a one-time outbound call using an AI phone agent. Use Sequences for scheduled or bulk calling.

Use this endpoint for a one-time call attempt. Requests are not queued for later execution.
For scheduled or bulk calling, use the [Sequences API](/api-reference/sequences/index).

Check both the HTTP status and the response body. A successful request does not mean the recipient answered; a setup failure can appear in the response body.

If the endpoint returns HTTP `429` or `503` with an `outbound_call_*` error, no call was started for that request. The endpoint does not retry it automatically or provide a `Retry-After` header. Your application decides whether to try again later.


# Redaction
Source: https://docs.open.cx/api-reference/redaction/index

The Redaction API allows you to programmatically redact sensitive content from chat messages and sessions.

The Redaction API allows you to programmatically redact sensitive content from chat messages and sessions.
This is essential for compliance with data protection regulations like GDPR, CCPA, and HIPAA, enabling you
to remove personally identifiable information (PII) and other sensitive data when required.

## Overview

Redaction in our system enables:

* **Message-Level Redaction** - Redact specific messages by message ID, including any attached images or files
* **Session-Level Redaction** - Redact all messages in an entire chat session, including all attachments
* **Compliance Support** - Meet data protection requirements by permanently removing sensitive content
* **Audit Trail** - All redaction actions are logged for compliance and security purposes
* **Attachment Handling** - Automatically handles redaction of images and file attachments

## Security & Compliance

<Warning>
  Redaction is **permanent and irreversible**. Once content is redacted, it cannot be recovered. The
  original content is replaced with "\[REDACTED]" and all associated files are marked as deleted.
</Warning>

* All redaction actions are logged in audit trails without exposing the original content
* File attachments are removed from the message and marked as deleted
* Redaction events are tracked with timestamps, user information, and reasons
* Original content is never stored in audit logs for security

## Redact selected content in the dashboard

In a session, open a message's menu and choose **Redact Message**. The message and a live preview
appear together. Turn on **Redact entire message** to remove all its text and attachments. Turn it
off to return to your previous selections.

To keep the rest of the message:

1. Leave **Redact entire message** off.
2. Hover over a word to see that it is clickable, then click to mark it. Click again to unmark it,
   or drag across a longer passage to mark it in one gesture. Use **Select all text** to mark the
   complete body without selecting attachments. Double-clicking has the same effect as one click.
   With a keyboard, use the arrow keys to move between words and Enter or Space to toggle one;
   Control+A or Command+A marks all text. The preview updates as you mark content.
   Use **Clear text selections** beside **Select all text** to start again.
3. Check the images or files you want to remove. Text and attachment selections can be combined.
4. Compare the message with **After redaction**. Open **Add a reason (optional)** if needed, then
   click **Redact selection**.

Selected passages become `[REDACTED]`. Other text and unselected attachments remain. Removing
the last attachment from a message without text leaves a redaction placeholder.
You can select up to 100 passages and 100 attachments per action. If you exceed either limit,
adjust your selections before submitting; your draft stays available. Failed submissions also
keep your draft until you refresh the message.
You need permission to read sessions and the **Redaction** write permission to use these controls.

<Warning>
  Redaction cannot be undone. Affected stored originals, translations, and linked email copies
  are also handled. Original versions that cannot be safely edited are removed. If a message
  changes while the dialog is open, refresh and select again. A linked copy that differs may
  require reviewing that copy or using entire-message redaction.
</Warning>

Selective redaction supports ordinary text, formatted messages, emails, and their attachments.
Structured messages, including template cards, require **Redact entire message**. An image is removed
as a whole; selecting an area inside an image is not supported.

Removing an OpenCX attachment blocks new access to that stored file, including shared references.
Previously issued download links remain valid until their existing expiry. Copies already
downloaded, delivered to external recipients, or hosted elsewhere are not removed. Search results
update through the usual search synchronization.

These selective controls are available in the dashboard. The public API and MCP redaction tools
continue to redact entire messages or sessions.

## Available Endpoints

<CardGroup>
  <Card title="Redact Message" icon="message" href="/api-reference/redaction/redact-message">
    Redact a specific message by message ID
  </Card>

  <Card title="Redact Session" icon="comments" href="/api-reference/redaction/redact-session">
    Redact all messages in a chat session
  </Card>
</CardGroup>


# Redact a specific message
Source: https://docs.open.cx/api-reference/redaction/redact-message

post /redaction/message
Redact a specific message by message ID, including any attached images. Use when applying or reversing PII redaction on a session or individual message.

For email sessions, redaction also removes saved email delivery copies and disables
existing retries in the affected session and sessions containing linked copies of
the redacted messages. This does not recall emails already delivered to recipients.

If an affected session is sending an email, or its linked history changes during
redaction, the request returns `409 Conflict` without applying the redaction. Retry
the redaction after the send completes or the history stops changing.


# Redact all messages in a session
Source: https://docs.open.cx/api-reference/redaction/redact-session

post /redaction/session
Redact all messages in a session by session ID, including any attached images. Use when applying or reversing PII redaction on a session or individual message.

For email sessions, redaction also removes saved email delivery copies and disables
existing retries in the affected session and sessions containing linked copies of
the redacted messages. This does not recall emails already delivered to recipients.

If an affected session is sending an email, or its linked history changes during
redaction, the request returns `409 Conflict` without applying the redaction. Retry
the redaction after the send completes or the history stops changing.


# List conversations that used a resource
Source: https://docs.open.cx/api-reference/resource-usage/conversations

get /resource-usage/{resource_type}/{resource_id}/conversations
Reverse lookup: list the conversations where a given action, instruction, or knowledge base item was used, newest first, with the reply count, ticket number, last message, and usage timestamps.



# Resource Usage
Source: https://docs.open.cx/api-reference/resource-usage/index

The Resource Usage API reports how often a given AI instruction, knowledge base item, or action was available to the AI and how often it was actually applied.

The Resource Usage API is a reverse lookup over AI-reply usage: given an action,
instruction, or knowledge base item, it answers **"where was this used?"** and
**"how often does it fire?"**.

## How Usage Is Tracked

Every AI reply records which resources were involved, with two usage kinds:

* **Available** — the resource was in the AI's context for the reply. For
  instructions and knowledge base items, this means it was eligible to be used.
* **Applied** ("used") — the resource was actually applied: an instruction or
  knowledge base item cited in the reply, or an action invoked. Actions are
  always recorded as applied (they only appear when called).

Comparing applied vs. available gives an **apply-rate** for instructions and
knowledge base items.

## Resource Types

The `resource_type` path parameter selects what to look up:

* `instruction` — an AI instruction / behavior
* `knowledge` — a knowledge base item
* `action` — a tool the AI can call

## Scopes

Both endpoints require the resource's own read scope plus `chat-sessions:read`
(the responses expose conversation data — session ids, ticket numbers, last
message):

* `instruction` / `knowledge` → `training:read` + `chat-sessions:read`
* `action` → `actions:read` + `chat-sessions:read`

## Available Endpoints

<CardGroup>
  <Card title="List Usage" icon="table-list" href="./list">
    Bulk available / applied / handoff counts for every resource of a type
  </Card>

  <Card title="Get Usage Summary" icon="chart-simple" href="./usage-summary">
    Aggregate available / applied counts for a single resource
  </Card>

  <Card title="List Conversations" icon="list" href="./conversations">
    List the conversations a resource was used in
  </Card>
</CardGroup>


# List usage counts for all resources of a type
Source: https://docs.open.cx/api-reference/resource-usage/list

get /resource-usage/{resource_type}
Bulk usage: one row per action, instruction, or knowledge base item with available and applied (used) counts, handoff count, and first/last-used timestamps, most recently used first.



# Get usage counts for a resource
Source: https://docs.open.cx/api-reference/resource-usage/usage-summary

get /resource-usage/{resource_type}/{resource_id}/usage-summary
Aggregate usage for one action, instruction, or knowledge base item: sessions and replies where it was applied, the available counterpart for apply-rate, and first/last-used timestamps.



# Salesforce MIAW
Source: https://docs.open.cx/api-reference/salesforce-miaw/index

Send Salesforce Messaging for In-App and Web (MIAW) events into OpenCX via webhook. Use to sync human-agent replies from Salesforce back into an OpenCX session.

## Overview

The Salesforce MIAW API allows you to sync human agent responses from Salesforce Messaging for In-App and Web (MIAW) into Open.

## Authentication

All endpoints require an API key with the `salesforce-miaw:write` scope. Pass it as a Bearer token in the `Authorization` header:

```bash theme={"dark"}
curl -X POST https://api.open.cx/salesforce/miaw/webhook \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"event": "message:new", "session_id": "your-session-id"}'
```

## Supported Events

| Event | Description |
| - | - |
| `message:new` | A new message was sent in a MIAW conversation |


# Webhook
Source: https://docs.open.cx/api-reference/salesforce-miaw/webhook

post /salesforce/miaw/webhook
POST /salesforce/miaw/webhook. Use when wiring Salesforce Messaging-for-In-App-and-Web events into OpenCX.



# Search
Source: https://docs.open.cx/api-reference/search/index

get /search
Query OpenCX for chat sessions, contacts, and training content from one endpoint. Use when building a custom search surface over organisation-wide data.



# Create a secret
Source: https://docs.open.cx/api-reference/secrets/create

post /secrets
Store a new named secret. The value is encrypted at rest and never returned. Fails with 409 if a secret with this name already exists.



# Secrets
Source: https://docs.open.cx/api-reference/secrets/index

The Secrets API lets you provision and rotate the named credentials your actions and workflows reference. It is write-only — a secret value is never returned by any endpoint.

The Secrets API lets you provision and rotate the named credentials your actions and workflows reference. Define a secret once, then point any number of actions at it by name instead of pasting the same token into each one.

<Warning>
  This API is **write-only**. No endpoint returns a secret's value, and there is
  no `secrets:read` scope. To change a secret you replace it; to inspect one you
  cannot — that is the point. A leaked API key can overwrite a credential (which
  shows up in your audit log) but can never read one back.
</Warning>

## Key Concepts

* **Name** — the reference key, unique per organization. Actions and workflows use it as `{{secrets.<name>}}`
* **Value** — the plaintext credential. Encrypted at rest and substituted server-side at execution time
* **Rotation** — writing the same name again replaces the value. Every action referencing it picks up the new value immediately; nothing needs re-pointing
* **Scope required** — `secrets:write` for both endpoints

## Referencing a secret

Once created, use the name in any action header or workflow field:

```
Authorization: Bearer {{secrets.stripe_key}}
```

OpenCX substitutes the value when the action runs. If the referenced secret does not exist, the whole header is dropped rather than sent half-resolved.

## Available Endpoints

<CardGroup>
  <Card title="Create Secret" icon="plus" href="./create">
    Store a new secret — fails with 409 if the name is taken
  </Card>

  <Card title="Create or Replace Secret" icon="rotate" href="./upsert">
    Idempotent write — creates the secret or rotates its value
  </Card>
</CardGroup>

## Deleting a secret

Deletion is available in the dashboard only, under **Settings → Secrets**. Removing a secret breaks every action still referencing it, so it stays behind the UI that shows you how many actions that is.


# Create or replace a secret
Source: https://docs.open.cx/api-reference/secrets/upsert

put /secrets
Create the secret or replace the value of the one already using this name. Idempotent — safe to call on every deploy to push the current credential.



# Enroll people into an outbound sequence — returns a per-person outcome
Source: https://docs.open.cx/api-reference/sequences/add-contacts

post /sequences/{sequenceId}/contacts
Enroll people by contact id, phone, email or WhatsApp user id and get one outcome per person. On an active sequence with steps they start sending right away.



# Continue the sequence for a person a reply took out of it
Source: https://docs.open.cx/api-reference/sequences/continue-contact

post /sequences/{sequenceId}/contacts/{contactId}/continue
Resume a contact who exited a sequence after replying, preserving their enrollment and skips. Understand when waiting restarts and why continuation can be refused.

Requires `sequences:write`. Resumes the same enrollment only when it exited because of a reply. Previously sent, completed, and [skipped steps](/api-reference/sequences/skip-step) are omitted. Personalization and journey history remain attached to that enrollment.

The next pending step's wait starts now. Any skipped waits between the current position and that step are added, applying the normal sending window at each slot. A skipped 30-minute call slot followed by a 60-minute email wait therefore takes at least 90 minutes from continuation. Future skips beyond an intervening pending step are honored when reached.

HTTP 201 returns `resumed`, `nothing_to_continue`, `not_resumable`, or `contact_not_found`. `not_resumable` includes a dispatch still in progress, active/parked/candidate enrollments, and suppression exits. Completed and removed enrollments are never revived. If every remaining slot is skipped, the enrollment stays exited and returns `nothing_to_continue`.

Continuing a contact does not activate a paused or draft sequence. Sending still depends on the sequence's lifecycle and normal consent checks.


# Create an outbound sequence, as a draft
Source: https://docs.open.cx/api-reference/sequences/create

post /sequences
Create an outbound sequence as a draft, with an optional brief, qualification criteria, settings and steps. Use as the first call of the enroll-first flow.



# List the attached-data keys a sequence's people carry
Source: https://docs.open.cx/api-reference/sequences/data-keys

get /sequences/{sequenceId}/data-keys
List the attached-data keys a sequence’s people carry, with how many people have a value at each. Use to find what a step variable can be bound to beyond the person columns.



# Semantic audience discovery — match a natural-language ask against what customers actually said, returning candidate people + evidence
Source: https://docs.open.cx/api-reference/sequences/discover

post /sequences/discovery/search
Find who to enroll from a natural-language ask, matched against what customers actually said in recent sessions. Returns candidate people with evidence, no fit judgment.



# Surgically edit steps — update content/delays, append, remove (any status)
Source: https://docs.open.cx/api-reference/sequences/edit-steps

patch /sequences/{sequenceId}/steps
Update, append or remove steps in one transactional batch, in any status. Use to change copy or delays on a live sequence without disturbing people mid-journey.

A recorded per-contact skip pins its step position. Removing that step or an earlier step is refused because it would change which step the contact skipped. Content and delay edits, and appending steps, remain available.


# Enrich scoped people from org data (async run)
Source: https://docs.open.cx/api-reference/sequences/enrich

post /sequences/{sequenceId}/enrich
Snapshot what the organization knows about scoped people (profile, sessions, insights, transcripts, segments) onto their rows for judging. Small scopes can be awaited.



# List the enrichment paths a sequence column may project
Source: https://docs.open.cx/api-reference/sequences/enrichment-catalog

get /sequences/enrichment-catalog
List every enrichment path a People-table column may project, with its resolved type. Use to pick valid column paths; anything outside the catalog is rejected.



# Remove one person from the sequence
Source: https://docs.open.cx/api-reference/sequences/exit-contact

post /sequences/{sequenceId}/contacts/exit
Stop every remaining step for one person, identified by contact id, email, phone or WhatsApp user id. Safe to fire in bulk: never-enrolled people return an outcome.



# Get an outbound sequence
Source: https://docs.open.cx/api-reference/sequences/get

get /sequences/{sequenceId}
Fetch one outbound sequence: status, steps, settings, brief, criteria and People-table columns. Use to read the current definition before editing it.



# One person's full record: verdicts, qualification, enrichment
Source: https://docs.open.cx/api-reference/sequences/get-contact

get /sequences/{sequenceId}/contacts/{contactId}
Read one person in full: identities, status, next step, the complete judgment with verdicts and citations, and the enrichment snapshot the judge saw.



# One person's journey ledger — every step outcome, oldest first
Source: https://docs.open.cx/api-reference/sequences/get-contact-events

get /sequences/{sequenceId}/contacts/{contactId}/events
Read the per-person ledger, oldest first: enrollment, sends, skips with reasons, deferrals, delivery and call outcomes, parks and exits, with inbox session ids.



# One run: status, live counts, completion aggregates
Source: https://docs.open.cx/api-reference/sequences/get-qualification-run

get /sequences/{sequenceId}/qualification-runs/{runId}
Read one enrich or judge run: status, live counts and, once complete, where passes, fails and unsures concentrate per criterion plus the fit distribution.



# Override a below-cutoff judgment ("include anyway")
Source: https://docs.open.cx/api-reference/sequences/include-contact

post /sequences/{sequenceId}/contacts/{contactId}/include
Override a below-cutoff judgment so the person arms at the next launch or enrollment wave. Verdicts stay on record and the override is written to the ledger.



# Sequences API
Source: https://docs.open.cx/api-reference/sequences/index

Run multi-step outbound journeys over WhatsApp, voice and email from code: enroll people, author steps, launch, and read what happened to each person.

A **sequence** is a multi-step outbound journey. Each person enrolled in it walks the steps in order, on the channel each step names (WhatsApp, an AI phone call, or email), waiting the step's delay between messages, and leaves the journey the moment they engage. The engine tracks every person individually, so a sequence is both a plan and a live record of what happened to each contact.

Every endpoint here is scoped with `sequences:read` or `sequences:write`. Three exceptions are called out below: audience discovery returns contact data and needs `contacts:read`, reply previews need `chat-sessions:read`, and adding someone who is not a contact yet creates one, which also needs `contacts:write`.

## Lifecycle

A sequence has three stored statuses:

| Status | Meaning |
| - | - |
| `draft` | Being authored. People can be enrolled and reviewed; nothing is sent. |
| `active` | Launched. Eligible people are armed and sent; new enrollees arm immediately. |
| `paused` | Sending is stopped. Everyone keeps their place and resumes from the same step. |

* [Launch](/api-reference/sequences/launch) moves `draft` to `active` and arms every eligible candidate. Launching an already active sequence is idempotent: it only arms candidates added since. Launching a paused sequence is refused, [resume](/api-reference/sequences/resume) it instead.
* [Pause](/api-reference/sequences/pause) and [resume](/api-reference/sequences/resume) only touch the sequence itself. People keep their cursors; on resume, overdue steps go first.
* There is no stored "done". `finished` on the stats is derived (nothing left in flight and something already went out), so enrolling more people revives a finished sequence with no status change.

## Recommended flow

The API is built for **enroll first, author later**: land a real audience, then write the steps for it.

<Steps>
  <Step title="Create the shell">
    [Create](/api-reference/sequences/create) with a name and a plain-text brief. Steps can wait.
  </Step>

  <Step title="Enroll people">
    [Add contacts](/api-reference/sequences/add-contacts) by contact id, phone, email or WhatsApp user id, with any facts you know about them in `extra_data`. To hand your own identifiers to the sessions the sequence opens — the call, or the session their reply lands in — put them in `session_custom_data`; they come back on the session as custom data, so a workflow on Call Finished or Ticket Created can update the record they point at. Read the per-person outcomes; a successful call never implies everyone was enrolled. Use `batch_key` to label the wave. [List contacts](/api-reference/sequences/list-contacts) to review who landed.
  </Step>

  <Step title="Author steps and bind senders">
    [Set steps](/api-reference/sequences/set-steps) on the draft. [Set senders](/api-reference/sequences/set-senders) per channel; the [email](/api-reference/sequences/list-email-senders) and [voice](/api-reference/sequences/list-voice-senders) catalogs tell you which senders are eligible and why not.
  </Step>

  <Step title="Preview, then launch">
    [Launch preview](/api-reference/sequences/launch-preview) mirrors launch clause for clause: who would start, who is held and why, and what would refuse the launch. Then [launch](/api-reference/sequences/launch).
  </Step>

  <Step title="Keep feeding it">
    Keep calling add contacts. On an active sequence with steps, new people arm the moment they are enrolled, so a CRM can push leads without anyone pressing launch again. [Remove](/api-reference/sequences/exit-contact) a person to stop every remaining step.
  </Step>
</Steps>

## People

Every person in a sequence has one status:

| Status | Meaning |
| - | - |
| `candidate` | Enrolled, not armed. Drafts hold everyone here; on an active sequence this is someone held back by a qualification verdict. |
| `active` | Armed. The engine sends their next step when it becomes due. |
| `parked` | Waiting on a human. `park_reason` says what to fix; the journey resumes where it stopped. |
| `exited` | Journey over. `exit_reason` is `replied` (they engaged) or `suppressed` (every channel they could be reached on is blocked). |
| `completed` | Every step has finished, including skipped or failed steps, and nobody replied. |

Park reasons are always something a person must fix: `needs_data` (a step variable has no value and no fallback), `unsendable_person` (their own data cannot go on the wire), or `template_broken` (the step's template is missing, rejected or mismatched for everyone).

A removal through [exit contact](/api-reference/sequences/exit-contact) is a deletion, not an exit reason. The person leaves every read, and adding them again later starts them fresh from the first step. What was already sent is kept.

Each person also carries a **journey**: one stamp per step (`not_reached`, `waiting`, `parked`, `deferred`, `skipped`, `sent`, `delivered`, `read`, `replied`, `answered`, `no_answer`, `busy`, `failed`) with the inbox session of the send when one exists. For the raw event log behind those stamps, read [contact events](/api-reference/sequences/get-contact-events).

### Skip a step for one contact

[Skip Sequence Step](/api-reference/sequences/skip-step) omits the next pending step, the next pending step on a channel, or a specific step for one contact. It preserves intervening outreach, personalization, and all waits. It does not resume a reply-exited contact or release an existing park.

After a reply such as “I cannot talk now,” skip the next **Phone** step and then [continue the same enrollment](/api-reference/sequences/continue-contact). Continuation counts the next pending step's wait and preceding skipped waits from resume time. A send already being dispatched cannot be skipped. See the [workflow setup](/phone/follow-up-workflows#skip-a-sequence-call-after-a-reply).

### Enrollment outcomes

Add contacts answers per person, index-aligned with what you sent:

| Outcome | Bucket | Meaning |
| - | - | - |
| `enrolled` | enrolled | New row created. |
| `updated` | enrolled | Existing candidate refreshed, or a parked person given new data, who resumes their step (armed at once on a live sequence, back to candidate on a draft). A parked person given only `session_custom_data` keeps it merged and stays parked. |
| `already_enrolled` | noop | Already active or completed here, or parked with nothing new supplied. |
| `skipped_previously_exited` | not enrolled | They exited this sequence before. An exit is terminal; enrolling never restarts a concluded journey. |
| `skipped_suppressed` | not enrolled | Every channel they could be reached on is on the [outbound blocklist](/api-reference/outbound-blocklist/index). |
| `skipped_active_elsewhere` | not enrolled | Active in another sequence (setting `block_active_elsewhere`, on by default). |
| `skipped_contacted_before` | not enrolled | Some sequence already messaged them (setting `block_contacted_before`, on by default). |
| `no_identity` | not enrolled | No valid phone, email or WhatsApp user id after normalization. `detail.dropped` names what was rejected. |
| `skipped_cannot_create_contact` | not enrolled | They match no existing contact, and the key lacks `contacts:write`, so no contact was created. Nothing written. |
| `extra_data_too_large` | not enrolled | The `extra_data` bag exceeds its budget. Nothing written; trim and retry that person. |
| `session_custom_data_too_large` | not enrolled | The `session_custom_data` bag, or its merge with what the person already holds, exceeds 50 keys or 8,000 characters. Nothing written; trim and retry that person. |
| `conflict` | not enrolled | The handles match two different existing people. `detail.matches` carries their contact ids. |
| `error` | not enrolled | This row failed unexpectedly. The rest of the batch is unaffected; retry that person. |

Phone numbers must be in international format, emails are lowercased, and duplicates inside one call are reported with `detail.in_batch`.

## Steps

A step is a channel, its content, and `delay_minutes`: how long to wait after the previous step **actually sent**. The first step must have a delay of zero because launch and enrollment arm it, not a timer.

<AccordionGroup>
  <Accordion title="WhatsApp step" icon="whatsapp">
    References an approved message template by `template_name` and `template_language`. `variables` is keyed by the template's body parameter: its positional index (`"1"`, `"2"`) or exact name (`"first_name"`, `"course_name"`), each bound to a source (see [Variables](#variables)) with an optional `fallback`. No value and no fallback parks the person; the engine never sends generic filler. A template still under review does not block a launch: armed people wait and send the moment it is approved. A rejected or disabled template refuses the launch.

    For an existing named template, bind every distinct body parameter by name, without the braces:

    ```json theme={"dark"}
    {
      "type": "whatsapp_template",
      "template_name": "course_followup",
      "template_language": "en",
      "variables": {
        "first_name": { "source": "display_name" },
        "course_name": { "source": "course_name" },
        "brand_name": { "source": "brand_name", "fallback": "Our team" }
      }
    }
    ```

    Supply `course_name` and `brand_name` through each person's attached data. Template sample values are only examples; they are not used as recipient data or automatic fallbacks. Missing or extra parameter bindings prevent sending. Repeated placeholders need only one binding.

    Named body parameters work with static text headers, static footers, and quick-reply buttons. Variable headers and media headers remain unsupported in sequences. Existing URL-suffix and coupon button bindings still use the button index.

    Per-person personalization uses the same exact keys in `values`, for example `{"first_name": "Tom", "course_name": "Biblical Hebrew", "brand_name": "Our team"}`. Include every body parameter with no extras; previews and sent-message history preserve these names. Positional templates continue to use numeric keys.

    The companion can use existing named templates. When creating a new WhatsApp template through the companion, use numbered placeholders such as `{{1}}` and `{{2}}`; its creation tool rejects named placeholders.
  </Accordion>

  <Accordion title="Voice step" icon="phone">
    The **call brief**: `extra_instructions` rendered per person and handed to the bound phone agent as call-only guidance. The agent carries the persona (voice, language, tone, tools); the step never overrides it. Both fields are optional for an agent whose persona already holds the whole mission. One step is one dial attempt per person, ever: to retry no-answers, author further voice steps with delays. An answered call is the reply and exits the journey.
  </Accordion>

  <Accordion title="Email step" icon="envelope">
    Inline `subject`, `html` and `text` (all three required). Every `{{name}}` placeholder must have a binding in `variables`; an unbound placeholder is refused at authoring time rather than shipped. `{{signature}}` is a system token filled from the sending mailbox and needs no binding.
  </Accordion>
</AccordionGroup>

Drafts take a full step list through [set steps](/api-reference/sequences/set-steps). Once launched, use [edit steps](/api-reference/sequences/edit-steps): content and delay updates are allowed on any step (people already past it keep what they received), appends are always allowed, and removing a step somebody already reached is refused. Changing a step's channel is a remove plus an append.

### Variables

Every variable binding is `{ "source", "fallback"?, "type"? }`. The `source` names where the value comes from for each person:

* `display_name`, `phone`, `email` read the person's own columns, as always.
* Any other string is the exact name of a key in the data attached to the person at enrollment (`extra_data` on [add contacts](/api-reference/sequences/add-contacts)): a spreadsheet column, a field a workflow or an integration sent. The key is matched verbatim, top level only. The three column names above always win over a same-named key.

A value that is empty falls to `fallback`; no fallback parks the person on `needs_data`, naming the source. Attached data is rendered by its `type`, the same vocabulary [columns](/api-reference/sequences/set-columns) use: without a `type`, text and numbers pass through and anything else counts as missing; with one, text is parsed where it is unambiguous (`"250"` as a number, `"true"` as a boolean, an ISO-shaped date such as `2026-03-12`; other date spellings and epoch numbers count as missing), a `date` reads as a plain day in the person's timezone (`12 Mar 2026`), a list must actually be a list in the data and joins with commas, a boolean reads Yes/No, and a value that cannot be read as the declared type counts as missing.

```json theme={"dark"}
"variables": {
  "name":    { "source": "display_name", "fallback": "there" },
  "company": { "source": "company",      "fallback": "your team" },
  "renewal": { "source": "renewal_at",   "type": "date" }
}
```

Attached data differs per person, so a key is never validated at authoring time. Instead, [set steps](/api-reference/sequences/set-steps) and [edit steps](/api-reference/sequences/edit-steps) answer with `variable_coverage`: for every bound source, how many enrolled people have a value, over a bounded sample. Zero on a populated sequence is almost always a misspelled key; a partial count means the variable needs a fallback or should go. [Data keys](/api-reference/sequences/data-keys) lists every key the sequence's people carry, most-covered first and up to 200, for a sequence whose people you did not enroll yourself. A value that cannot go on the wire for its channel — a line break, or, on WhatsApp, values that together push the filled-in message past its length limit — parks that person as `unsendable_person` rather than being altered; the largest value is named.

## Senders

Each channel needs at least one bound sender before launch: WhatsApp numbers, AI phone agents for calls, mailboxes for email. [Set senders](/api-reference/sequences/set-senders) replaces the binding for one channel. Unbinding the last sender of a channel while an active sequence still has sends pending on it is refused; pause first.

The [email](/api-reference/sequences/list-email-senders) and [voice](/api-reference/sequences/list-voice-senders) catalogs report eligibility and the reason when a sender cannot be bound. Email health numbers are information beside eligibility, never a gate.

## Settings

| Setting | Default | Effect |
| - | - | - |
| `block_active_elsewhere` | on | Skip people currently active in another sequence. |
| `block_contacted_before` | on | Skip people any sequence already messaged. |
| `respect_office_hours` | on | Send only inside the send window. Off means send any time. |
| `office_hours_id` | org default | A named office-hours schedule to use instead of the org default. Null on update clears it. |

Settings are read live by the engine, so a change applies to the next send decision in any status.

## Qualification

A sequence can also carry qualification criteria and run an [enrich](/api-reference/sequences/enrich) and [judge](/api-reference/sequences/judge) pass over its people. Those endpoints exist for the assistant-driven authoring flow and are not needed to run a sequence from the API: people you enroll and never judge always arm. The endpoint pages under Qualification describe them.

## Consent

The engine enforces the [outbound blocklist](/api-reference/outbound-blocklist/index) at enrollment, at launch, and again before every single send. If the blocklist cannot be read, the send is held rather than released.

## Available endpoints

<CardGroup>
  <Card title="Create sequence" icon="plus" href="/api-reference/sequences/create">Create a draft with brief, criteria and settings</Card>
  <Card title="List sequences" icon="list" href="/api-reference/sequences/list">Every sequence with its live numbers</Card>
  <Card title="Get sequence" icon="magnifying-glass" href="/api-reference/sequences/get">One sequence's definition</Card>
  <Card title="Update sequence" icon="pen" href="/api-reference/sequences/update">Name, brief, criteria, reply instructions, settings</Card>
  <Card title="Set steps" icon="list-ol" href="/api-reference/sequences/set-steps">Replace the step list of a draft</Card>
  <Card title="Edit steps" icon="pen-to-square" href="/api-reference/sequences/edit-steps">Update, append or remove steps in any status</Card>
  <Card title="Update step delay" icon="clock" href="/api-reference/sequences/update-step-delay">Change one step's wait</Card>
  <Card title="Add contacts" icon="user-plus" href="/api-reference/sequences/add-contacts">Enroll people with per-person outcomes</Card>
  <Card title="List contacts" icon="users" href="/api-reference/sequences/list-contacts">Paginated people with status, fit and journey</Card>
  <Card title="Get contact" icon="user" href="/api-reference/sequences/get-contact">Full judgment and enrichment for one person</Card>
  <Card title="Get contact events" icon="timeline" href="/api-reference/sequences/get-contact-events">The per-person ledger</Card>
  <Card title="Update contact" icon="user-pen" href="/api-reference/sequences/update-contact">Correct a name or handle</Card>
  <Card title="Include anyway" icon="circle-check" href="/api-reference/sequences/include-contact">Override a below-cutoff judgment</Card>
  <Card title="Remove contact" icon="user-minus" href="/api-reference/sequences/exit-contact">Stop every remaining step for one person</Card>
  <Card title="Launch preview" icon="eye" href="/api-reference/sequences/launch-preview">What launching would do</Card>
  <Card title="Launch" icon="rocket" href="/api-reference/sequences/launch">Arm eligible candidates</Card>
  <Card title="Pause" icon="pause" href="/api-reference/sequences/pause">Stop sending, keep places</Card>
  <Card title="Resume" icon="play" href="/api-reference/sequences/resume">Make people sendable again</Card>
  <Card title="Get stats" icon="chart-simple" href="/api-reference/sequences/stats">Numbers plus who is stuck and why</Card>
  <Card title="List replies" icon="reply" href="/api-reference/sequences/replies">Who answered, newest first</Card>
  <Card title="List senders" icon="address-card" href="/api-reference/sequences/list-senders">Senders bound per channel</Card>
  <Card title="Set senders" icon="arrows-rotate" href="/api-reference/sequences/set-senders">Replace one channel's senders</Card>
  <Card title="List email senders" icon="envelope" href="/api-reference/sequences/list-email-senders">Mailboxes with eligibility and health</Card>
  <Card title="List voice senders" icon="phone" href="/api-reference/sequences/list-voice-senders">Phone agents with eligibility and persona</Card>
  <Card title="Enrich contacts" icon="database" href="/api-reference/sequences/enrich">Snapshot what the org knows about people</Card>
  <Card title="Judge contacts" icon="gavel" href="/api-reference/sequences/judge">Score people against the criteria</Card>
  <Card title="List qualification runs" icon="list-check" href="/api-reference/sequences/list-qualification-runs">Enrich and judge runs, latest first</Card>
  <Card title="Get qualification run" icon="chart-pie" href="/api-reference/sequences/get-qualification-run">One run's counts and aggregates</Card>
  <Card title="Set columns" icon="table-columns" href="/api-reference/sequences/set-columns">Project evidence into the People table</Card>
  <Card title="Enrichment catalog" icon="book" href="/api-reference/sequences/enrichment-catalog">Paths a column may project</Card>
  <Card title="Data keys" icon="key" href="/api-reference/sequences/data-keys">Attached-data keys a variable can bind to</Card>
  <Card title="Discover contacts" icon="wand-magic-sparkles" href="/api-reference/sequences/discover">Find an audience from what customers said</Card>
</CardGroup>


# Judge scoped people against criteria (async run)
Source: https://docs.open.cx/api-reference/sequences/judge

post /sequences/{sequenceId}/judge
Judge scoped people against the criteria over their stored enrichment: must-haves gate, nice-to-haves rank, fit lands on each row. Await a sample to tune criteria.



# Launch an outbound sequence — arms candidates for sending
Source: https://docs.open.cx/api-reference/sequences/launch

post /sequences/{sequenceId}/launch
Activate a draft sequence and arm every eligible candidate. Re-launching an active sequence only arms people added since; a paused one must be resumed instead.



# What launching WOULD do, without doing it
Source: https://docs.open.cx/api-reference/sequences/launch-preview

get /sequences/{sequenceId}/launch-preview
See what launching would do before doing it: forecast of who starts sending, who is held and why, blockers that refuse the launch, and templates still in review.



# List outbound sequences
Source: https://docs.open.cx/api-reference/sequences/list

get /sequences
List every outbound sequence in the organization with its live numbers: audience, will send, sent, replied, unreachable and needs-you counts.



# List a campaign's people (paginated summary rows)
Source: https://docs.open.cx/api-reference/sequences/list-contacts

get /sequences/{sequenceId}/contacts
Page through the people in a sequence with status, fit, judgment tallies, projected columns and a per-step journey. Filter by status, judgment band or batch key.



# List the mailboxes this org can bind as sequence email senders
Source: https://docs.open.cx/api-reference/sequences/list-email-senders

get /sequences/email-senders
List the mailboxes this organization can bind as email senders, each with an eligibility verdict and health numbers such as warm-up status and bounce share.



# List a campaign's enrich/judge runs, latest first
Source: https://docs.open.cx/api-reference/sequences/list-qualification-runs

get /sequences/{sequenceId}/qualification-runs
List a sequence’s enrich and judge runs, latest first, with status, scope, live counts and completion aggregates. Use to follow long runs or audit past ones.



# List the senders bound to a sequence
Source: https://docs.open.cx/api-reference/sequences/list-senders

get /sequences/{sequenceId}/senders
List the senders bound to a sequence per channel: WhatsApp numbers, phone agents for calls, and mailboxes for email. Use to confirm a sequence can send.



# List the phone agents this org can bind as sequence voice senders
Source: https://docs.open.cx/api-reference/sequences/list-voice-senders

get /sequences/voice-senders
List the AI phone agents this organization can bind as voice senders, with eligibility, caller number, opening line and persona so you pick the right agent.



# Pause an outbound sequence — sending stops now; people keep their place
Source: https://docs.open.cx/api-reference/sequences/pause

post /sequences/{sequenceId}/pause
Stop all sending for an active sequence immediately. Everyone keeps their place in the journey and continues from the same step when the sequence resumes.



# List the most recent replies to a sequence
Source: https://docs.open.cx/api-reference/sequences/replies

get /sequences/{sequenceId}/replies
List the most recent replies to a sequence, newest first, with the inbox session each one started. Previews require a key that may read conversations.



# Resume a paused sequence
Source: https://docs.open.cx/api-reference/sequences/resume

post /sequences/{sequenceId}/resume
Resume a paused sequence so people become sendable again, overdue steps first. Use after a pause; launching a paused sequence is refused.



# Set the columns the sequence's People table shows
Source: https://docs.open.cx/api-reference/sequences/set-columns

put /sequences/{sequenceId}/columns
Set the columns the People table shows, projected from each person’s enrichment or caller-supplied extra data by path. Use to surface the evidence behind fit.



# Set the senders a sequence may send from (replace-set per channel)
Source: https://docs.open.cx/api-reference/sequences/set-senders

put /sequences/{sequenceId}/senders
Replace the senders a sequence may send from on one channel. Use before launching; unbinding the last sender of a channel with pending sends is refused.



# Replace the step list of a DRAFT sequence
Source: https://docs.open.cx/api-reference/sequences/set-steps

put /sequences/{sequenceId}/steps
Replace the whole step list of a draft sequence. Use when authoring steps after enrolling and qualifying the audience; launched sequences use edit steps.

A draft with recorded per-contact skips cannot have its step list fully replaced. Use [step edits](/api-reference/sequences/edit-steps) to preserve those step positions.


# Skip one pending step for a contact
Source: https://docs.open.cx/api-reference/sequences/skip-step

post /sequences/{sequenceId}/contacts/{contactId}/skip-step
Skip one pending step for a contact while preserving their enrollment, remaining outreach, and waits. Use before continuing a sequence after a reply.

Requires `sequences:write`. This operation changes one contact's enrollment. It keeps the enrollment ID, previous sends, personalization, and history, and leaves the shared sequence unchanged.

## Choose the pending step

| `mode` | Additional input | Selection |
| - | - | - |
| `next_pending` | None | First pending step at or after the contact's current position, on any channel. |
| `next_channel` | `channel`: `voice`, `whatsapp`, or `email` | First pending step on that channel. Phone is `voice`. Intervening steps stay in place. |
| `specific_step` | `step_index`: nonnegative integer | That sequence position, starting at zero. |

A pending step has not been sent, completed, or skipped. A failed attempt that remains retryable is still pending once dispatch has finished. A step that is being sent returns `dispatch_in_progress`; the request does not cancel it. Missing mode-dependent inputs, invalid channels, and negative or fractional indexes return HTTP 400. Inputs for another mode are ignored.

A phone call that connected is already sent even if its sequence send record is still being reconciled. An unresolved dial cannot be skipped or continued past until its outcome is known.

The optional `reason` is a nonempty string up to 2,000 characters. The contact's [journey history](/api-reference/sequences/get-contact-events) records the step, channel, reason, timestamp, and workflow, operator, or API-key attribution. Without a reason, history shows “Requested skip.” The journey shows **Skipped**, including future steps.

## Status and waiting time

* **Active:** the current due time stays in place. At that time the skipped slot is consumed and the next step's wait begins. Future skips take effect when reached.
* **Parked:** status and park reason stay unchanged. Resolve the existing park through its normal controls before the sender progresses.
* **Exited after a reply:** the skip is saved, but the enrollment stays exited. Call [Continue Sequence for Contact](/api-reference/sequences/continue-contact) separately.
* **Completed, suppressed, removed, or candidate:** no step is newly skipped and no enrollment is revived.

Sequence pauses and consent restrictions still apply when the sender reaches a recorded skip. A temporary restriction covering every available channel defers progress until it expires; permanent suppression covering every available channel exits the enrollment.

Skipped steps retain their waits. A 30-minute wait before a skipped call followed by a 60-minute wait before an email keeps a 90-minute gap. Sending windows are applied at each slot in the contact's timezone, using the sequence's normal timezone fallback. Closed hours can lengthen the gap; later processing can also delay it.

Continuation starts waiting **when the contact is resumed**. It adds the waits of skipped slots before the next pending step, applying the same sending windows. In the example, the email becomes due no earlier than 90 minutes after continuation. If no pending steps remain, continuation returns `nothing_to_continue` and the enrollment stays exited.

If you later edit the pending step's wait, it is recalculated from the latest continuation or the previous step's effective completion time. Other history events do not restart that wait.

## Results and retries

The response uses HTTP 201 for both a new skip and an expected no-op:

```json theme={"dark"}
{
  "outcome": "skipped",
  "skipped": true,
  "contact_id": "01960000-0000-7000-8000-000000000002",
  "enrollment_id": "01960000-0000-7000-8000-000000000003",
  "step_index": 2,
  "channel": "voice"
}
```

| Outcome | Meaning |
| - | - |
| `skipped` | This request newly skipped the identified step. |
| `already_skipped` | The step or idempotent request was already applied. Original history is retained. |
| `contact_not_found` | No live enrollment, including a removed enrollment. |
| `not_skippable` | The enrollment is completed, suppressed, a candidate, or otherwise ineligible. |
| `no_pending_step` | No pending step matches the next-step selection. |
| `step_not_found` | The specific index is outside this sequence. |
| `step_not_pending` | The specific step was already sent, completed, or passed. |
| `dispatch_in_progress` | Sending has started and cannot safely be skipped. Wait for its outcome before retrying. |

`skipped` is true only for a new skip. Index/channel fields identify the selected step where available; otherwise they are null. A missing or inaccessible sequence returns HTTP 404; insufficient scope returns HTTP 403.

Specific-step requests are always idempotent. For either next-step mode, supply an `idempotency_key` of up to 200 characters and reuse it on retries. The key is scoped to this enrollment and identifies the original selection, even if the cursor later moves. Use a new key for a new skip intent. Workflow executions supply a key automatically for each action in a run.

Recorded skips pin their step positions: removing that shared step or an earlier step is refused. Full replacement of a draft containing recorded skips is also refused. Use content/delay edits or append steps instead.

The MCP equivalent is `skip_sequence_step`, with `sequence_id`, `contact_id`, and the same body fields.

## Skip the next phone step

```json theme={"dark"}
{
  "mode": "next_channel",
  "channel": "voice",
  "reason": "Customer cannot talk now",
  "idempotency_key": "reply-123-skip-phone"
}
```

After `skipped` or `already_skipped`, continue the same contact using the separate continuation operation. See the [workflow example](/phone/follow-up-workflows#skip-a-sequence-call-after-a-reply).


# Get an outbound sequence's numbers
Source: https://docs.open.cx/api-reference/sequences/stats

get /sequences/{sequenceId}/stats
Read one sequence’s numbers plus who will never be reached and who is waiting on a human, with reasons. Use to act on stuck people rather than just count them.



# Update a sequence — name, brief, criteria, reply instructions, settings
Source: https://docs.open.cx/api-reference/sequences/update

patch /sequences/{sequenceId}
Change a sequence name, brief, reply instructions, criteria or settings. Partial update allowed in any status; steps are edited through their own endpoints.



# Correct a person's name or the handles the sequence sends to
Source: https://docs.open.cx/api-reference/sequences/update-contact

patch /sequences/{sequenceId}/contacts/{contactId}
Correct a person’s display name, phone, email or WhatsApp user id while they are a candidate or parked. Use to fix bad data before the next send.



# Change how long a step waits before it sends
Source: https://docs.open.cx/api-reference/sequences/update-step-delay

patch /sequences/{sequenceId}/steps/{stepIndex}/delay
Change how many minutes a step waits after the previous message actually sent. Use to slow down or speed up one step; the first step always waits zero.



# SIP Integration
Source: https://docs.open.cx/api-reference/sip/index

SIP trunk provisioning is currently managed from the OpenCX dashboard, not the public API.

SIP trunk provisioning is currently managed from the OpenCX dashboard, not the public API. Use **[Settings → SIP](https://platform.open.cx/settings/sip)** to create inbound trunks, outbound trunks, and transfer destinations.

<Info>
  The previous SIP API examples documented `/phone/sip/...` endpoints that are not registered in the public API. They have been removed until SIP provisioning is exposed publicly.
</Info>

For setup steps, see [SIP Integration](/phone/sip-integration). After SIP is configured in the dashboard, the public [Phone API](/api-reference/phone/create) can list your transfer destinations ([GET /phone/transfer-destinations](/api-reference/phone/list_transfer_destinations)), attach them to a phone agent via `transfer_destination_ids`, create phone agents, and start outbound calls.


# Get SLA breach heatmap
Source: https://docs.open.cx/api-reference/sla-analytics/breach-heatmap

get /sla/analytics/breach-heatmap
Get a heatmap of SLA breaches by hour of day and day of week. Use when pulling SLA-adherence metrics into a reporting system.



# Get SLA analytics breakdown
Source: https://docs.open.cx/api-reference/sla-analytics/breakdown

get /sla/analytics/breakdown
Get SLA analytics breakdown — Get SLA compliance rates grouped by policy, team, agent, or channel.



# SLA Analytics
Source: https://docs.open.cx/api-reference/sla-analytics/index

SLA analytics provide visibility into your organization''s SLA compliance, response and resolution times, and breach patterns.

SLA analytics provide visibility into your organization's SLA compliance, response and resolution times, and breach patterns. Use this data to monitor service level performance and identify areas for improvement.

## What are SLAs?

Service Level Agreements (SLAs) define the expected response and resolution times for customer support interactions. The SLA analytics API lets you track:

* **Compliance rates** — How often your team meets SLA targets for first response and resolution
* **Coverage** — What percentage of sessions are covered by an SLA policy
* **Percentiles** — Response and resolution time distributions (p50, p75, p90, p95)
* **Trends** — How compliance changes over time
* **Breach patterns** — When SLA breaches are most likely to occur

## Available Endpoints

<CardGroup>
  <Card title="Overview" icon="chart-pie" href="/api-reference/sla-analytics/overview">
    Get SLA compliance rates, coverage, and response/resolution time percentiles
  </Card>

  <Card title="Breakdown" icon="chart-bar" href="/api-reference/sla-analytics/breakdown">
    Get SLA compliance grouped by policy, team, agent, or channel
  </Card>

  <Card title="Trend" icon="chart-line" href="/api-reference/sla-analytics/trend">
    Get SLA compliance rates over time, grouped by day or week
  </Card>

  <Card title="Breach Heatmap" icon="fire" href="/api-reference/sla-analytics/breach-heatmap">
    Get a heatmap of SLA breaches by hour of day and day of week
  </Card>
</CardGroup>


# Get SLA analytics overview
Source: https://docs.open.cx/api-reference/sla-analytics/overview

get /sla/analytics
Get SLA analytics overview — Get SLA compliance rates, coverage rate, and response/resolution time percentiles for a date range.



# Get SLA analytics trend
Source: https://docs.open.cx/api-reference/sla-analytics/trend

get /sla/analytics/trend
Get SLA analytics trend — Get SLA compliance rates over time, grouped by day or week.



# Get auto-tagging status
Source: https://docs.open.cx/api-reference/tags/auto_tagging_get

get /tags/auto-tagging
Get auto-tagging status — Check whether AI auto-tagging is enabled for your organization.



# Enable or disable auto-tagging
Source: https://docs.open.cx/api-reference/tags/auto_tagging_set

put /tags/auto-tagging
Enable or disable auto-tagging — Turn AI auto-tagging on or off. Use when managing the tag vocabulary your agents apply — e.g. when syncing a taxonomy from a CRM.



# Create a tag category
Source: https://docs.open.cx/api-reference/tags/categories/create

post /tags/categories
Create a tag category to group related tags. Use when syncing a taxonomy from a CRM or organizing tags for AI auto-tagging.



# Delete a tag category
Source: https://docs.open.cx/api-reference/tags/categories/delete

delete /tags/categories/{id}
Delete a tag category from your organization. Tags previously assigned to it become uncategorized; the tags themselves are kept.



# List tag categories
Source: https://docs.open.cx/api-reference/tags/categories/list

get /tags/categories
List or search tag categories for your organization. Filter by keyword (name/description) and limit when browsing a large taxonomy.



# Update a tag category
Source: https://docs.open.cx/api-reference/tags/categories/update

put /tags/categories/{id}
Update a tag category name or description. Use when refining taxonomy guidance for AI auto-tagging.



# Delete a tag
Source: https://docs.open.cx/api-reference/tags/delete

delete /tags/{tag_name}
Delete a tag — Remove a tag from your organization. Use when managing the tag vocabulary your agents apply — e.g. when syncing a taxonomy from a CRM.



# List tags in use
Source: https://docs.open.cx/api-reference/tags/in_use

get /tags/in-use
List tags in use — List all distinct tag names that are actually applied to sessions.



# Tags
Source: https://docs.open.cx/api-reference/tags/index

The Tags API lets you manage tags and tag categories for your organization and control AI auto-tagging.

The Tags API lets you manage tags and tag categories for your organization and control AI auto-tagging. Tags categorize chat sessions (e.g. "billing", "refund", "feature-request") and help with filtering, reporting, and routing.

## Key Concepts

* **Tag** — A label that can be applied to chat sessions, with an optional description and auto-tagging setting
* **Tag category** — A group of related tags (e.g. "Billing", "Product Area") so the AI can tag scalably across large taxonomies
* **Tags in use** — Tags that are actually applied to sessions
* **Auto-tagging** — When enabled, the AI automatically applies relevant tags to sessions based on conversation content
* **Search** — List endpoints accept optional `search`, `category_id` (tags only), and `limit` query params for substring filtering

## Available Endpoints

<CardGroup>
  <Card title="List / Search Tags" icon="list" href="./list">
    List or search tags (filter by keyword, category, limit)
  </Card>

  <Card title="Tags in Use" icon="chart-bar" href="./in_use">
    List tags currently applied to sessions
  </Card>

  <Card title="Create/Update Tag" icon="plus" href="./upsert">
    Create or update a tag
  </Card>

  <Card title="Delete Tag" icon="trash" href="./delete">
    Remove a tag
  </Card>

  <Card title="List / Search Categories" icon="folder-tree" href="./categories/list">
    List or search tag categories
  </Card>

  <Card title="Create Category" icon="folder-plus" href="./categories/create">
    Create a tag category
  </Card>

  <Card title="Update Category" icon="pen" href="./categories/update">
    Update a tag category
  </Card>

  <Card title="Delete Category" icon="folder-minus" href="./categories/delete">
    Delete a tag category
  </Card>

  <Card title="Auto-tagging Status" icon="robot" href="./auto_tagging_get">
    Check if AI auto-tagging is enabled
  </Card>

  <Card title="Toggle Auto-tagging" icon="toggle-on" href="./auto_tagging_set">
    Enable or disable AI auto-tagging
  </Card>
</CardGroup>


# List tags
Source: https://docs.open.cx/api-reference/tags/list

get /tags
List or search tags for your organization. Filter by keyword (name/description), category_id, and limit when syncing or browsing a large taxonomy.



# Create or update a tag
Source: https://docs.open.cx/api-reference/tags/upsert

put /tags
Create a new tag or update an existing one. Use when managing the tag vocabulary your agents apply — e.g. when syncing a taxonomy from a CRM.



# Add user to team
Source: https://docs.open.cx/api-reference/teams/add_user

post /teams/{teamId}/users
Add a user to an existing team. Use when syncing team structure between OpenCX and your organisation's identity/HR source of truth.



# Create new team
Source: https://docs.open.cx/api-reference/teams/create

post /teams
Create a new team in the organization. Use when syncing team structure between OpenCX and your organisation's identity/HR source of truth.

Configure [telephony pacing, distribution, and wrap-up](/api-reference/teams#telephony-policy) with the optional team policy fields.

Optionally set `category_id` to a category from the same workspace. See [team categories](/api-reference/teams#team-categories) for defaults, clearing a category, and validation.


# Create a team category
Source: https://docs.open.cx/api-reference/teams/create_category

post /teams/categories
Create a reusable team category in the current workspace, such as Telephony or Chat. Use the returned category ID when creating or updating teams.

Requires `teams:write`. Supply a `name` of 1–80 characters after trimming surrounding whitespace. Blank names and longer names return `400`.

The response contains the category's `id` and `name`. If the name already exists in this workspace, ignoring capitalization and surrounding spaces, the existing category is returned. Both outcomes return `201`; teams are not created or assigned automatically.


# Delete team
Source: https://docs.open.cx/api-reference/teams/delete

delete /teams/{teamId}
Delete an existing team. Use when syncing team structure between OpenCX and your organisation's identity/HR source of truth.



# Get specific team
Source: https://docs.open.cx/api-reference/teams/get

get /teams/{teamId}
Get specific team — Retrieve details of a specific team. Use when syncing team structure between OpenCX and your organisation's identity/HR source of truth.



# Get all teams
Source: https://docs.open.cx/api-reference/teams/get_all

get /teams
Get all teams — Retrieve all teams for the organization. Use when syncing team structure between OpenCX and your organisation's identity/HR source of truth.



# Get users in team
Source: https://docs.open.cx/api-reference/teams/get_users

get /teams/{teamId}/users
Get users in team — Retrieve all users in a specific team, including their availability and chat capacity for routing.



# Teams
Source: https://docs.open.cx/api-reference/teams/index

The Teams API allows you to programmatically manage user teams within your organization.

The Teams API allows you to programmatically manage user teams within your organization.
Teams are used to organize users, manage permissions, and automate task assignments, making it easier
to handle customer support and insights effectively.

## Overview

Teams in our system enable:

* **Permission Management** - Control access to features and data based on team membership
* **Support Hours & Team Assignment** - Define support schedules and automatically route customer inquiries to the right team
* **Automated Task Assignment** - Automatically assign customer insights and AI recommendations to specific teams
* **Team Organization** - Structure your support and operations teams efficiently

## Assignment pacing

Teams on the **Least busy** assignment strategy can space out the sessions they hand to each agent.
Set `auto_assign_interval_seconds` on the team to either `0` to turn pacing off, or any whole number
of seconds from `15` to `3600`.

With pacing on, an agent receives the first waiting session right away and then at most one more per
interval, so a sudden queue does not land on one person all at once. Sessions that have to wait are
assigned to the next agent who becomes available.

In the dashboard the same setting appears as **Assignment pacing** under **Settings → Teams**.

## Telephony policy

Create and update accept the following optional fields. Reads return the effective stored settings. Updating requires `teams:write`; reading requires `teams:read`. Omitted policy fields preserve existing values.

| Field | Values | Creation default |
| - | - | - |
| `telephony_pacing_enabled` | Boolean | `false` |
| `telephony_distribution` | `longest_available`, `fewest_answered_today` | `longest_available` |
| `telephony_ring_seconds` | Integer, 10–120 | `30` |
| `telephony_queue_wait_seconds` | Integer, 30–3,600 | `300` |
| `call_wrap_up_seconds` | `null` or integer, 0–3,600 | `null` |

`null` restores inherited organization wrap-up; `0` disables it for the team's calls. Pacing applies when a call is routed to a team destination: callers wait for that team, with one agent offered each call at a time. The organization ring percentage applies when pacing is off. See [team queues and distribution](/phone/call-answering#team-queues-and-telephony-pacing) for eligibility, fairness, timeouts, and settings captured for existing calls.

## Available Endpoints

<CardGroup>
  <Card title="Get Specific Team" icon="magnifying-glass" href="/api-reference/teams/get">
    Get detailed information about a specific team
  </Card>

  <Card title="Create Team" icon="plus" href="/api-reference/teams/create">
    Create a new team
  </Card>

  <Card title="Update Team" icon="pen" href="/api-reference/teams/update">
    Update an existing team
  </Card>

  <Card title="Delete Team" icon="trash" href="/api-reference/teams/delete">
    Delete a team
  </Card>

  <Card title="Get All Teams" icon="list" href="/api-reference/teams/get_all">
    Get all teams in the organization
  </Card>

  <Card title="Add User to Team" icon="user-plus" href="/api-reference/teams/add_user">
    Add a user to a team
  </Card>

  <Card title="Remove User from Team" icon="user-minus" href="/api-reference/teams/remove_user">
    Remove a user from a team
  </Card>
</CardGroup>

## Team categories

Create categories in [Settings → Teams](/teams) or with [Create category](/api-reference/teams/create_category). Use [List categories](/api-reference/teams/list_categories) to find category IDs. Team reads include `category_id`, which is `null` for an uncategorized team. Create and update accept an optional `category_id` belonging to the same workspace. Send `null` to clear it; omit it on update to preserve it. An unknown category or one belonging to another workspace returns `400`. Categories organize the team list and do not affect assignment or call routing.

Office hours assigned through `support_office_hours_id` must belong to the current workspace. An unknown, malformed, or foreign schedule returns `400` without changing the team. Send `null` to restore the workspace default; omit the field to preserve its current value.


# List team categories
Source: https://docs.open.cx/api-reference/teams/list_categories

get /teams/categories
List team categories in the current workspace, including unused categories. Use the returned IDs to organize teams and configure category assignments.

Requires `teams:read`. Returns only categories in the current workspace, sorted by name. Categories remain available even when no team uses them.

Assign a category using `category_id` in [create team](/api-reference/teams/create) or [update team](/api-reference/teams/update).


# Remove user from team
Source: https://docs.open.cx/api-reference/teams/remove_user

delete /teams/{teamId}/users/{userId}
Remove a user from a team. Use when syncing team structure between OpenCX and your organisation's identity/HR source of truth.



# Update team
Source: https://docs.open.cx/api-reference/teams/update

put /teams/{teamId}
Update an existing team. Use when syncing team structure between OpenCX and your organisation's identity/HR source of truth.

Configure [telephony pacing, distribution, and wrap-up](/api-reference/teams#telephony-policy) with the optional team policy fields.

Send only the fields you want to change. All fields, including `name`, are optional when updating a team; omitted fields stay unchanged. Creating a team still requires a name. An update must contain at least one recognized field; empty bodies or bodies containing only unknown fields return `400` without changing the team.

For example, to enable support without changing the team name or other settings:

```json theme={"dark"}
{
  "is_support_enabled": true
}
```

Optionally set `category_id` to a category from the same workspace. See [team categories](/api-reference/teams#team-categories) for defaults, clearing a category, and validation.


# Create a training
Source: https://docs.open.cx/api-reference/training/create

post /training
Create a new training scenario. Use when pushing training scenarios or knowledge into the AI training index from an external pipeline.



# Create a training directory
Source: https://docs.open.cx/api-reference/training/create_directory

post /training/directories
Create a training directory — Create a new directory for organizing trainings. Use when pushing training scenarios or knowledge into the AI training index from an external…



# Delete a training
Source: https://docs.open.cx/api-reference/training/delete

delete /training/{id}
Permanently delete a training. Use when pushing training scenarios or knowledge into the AI training index from an external pipeline.



# Delete a training directory
Source: https://docs.open.cx/api-reference/training/delete_directory

delete /training/directories/{directory_id}
Delete a training directory and all trainings inside it. Use when pushing training scenarios or knowledge into the AI training index from an external pipeline.



# Generate scenario
Source: https://docs.open.cx/api-reference/training/generate_scenario

get /training/generate-scenario/{session_id}
Generate scenario. Use when pushing training scenarios or knowledge into the AI training index from an external pipeline.



# Get a training
Source: https://docs.open.cx/api-reference/training/get

get /training/{id}
Get a single training by ID. Use when pushing training scenarios or knowledge into the AI training index from an external pipeline.



# List all trainings
Source: https://docs.open.cx/api-reference/training/get_all

get /training
List all trainings — List all training scenarios for your organization. Use when pushing training scenarios or knowledge into the AI training index from an external pipeline.



# Get directory tree
Source: https://docs.open.cx/api-reference/training/get_directory_tree

get /training/directories/tree
Get directory tree — Get all directories with their trainings, plus uncategorized trainings.



# AI Training
Source: https://docs.open.cx/api-reference/training/index

The AI Training API allows you to programmatically manage training scenarios, directories, and knowledge search for your AI assistant.

The AI Training API allows you to programmatically manage training scenarios, directories, and knowledge search for your AI assistant. Training scenarios teach the AI how to respond to specific situations unique to your business.

## Training Types

* **Behavioral** — Always-active instructions that control tone, style, guardrails, and escalation rules. Included in every conversation.
* **Scenario-specific** — Triggered by semantic matching when a customer's question is similar. Indexed as vector embeddings for retrieval.

## Key Concepts

* **Scenarios** — Question-answer pairs with a title (trigger) and body (instruction). Can be restricted to specific channels or contact segments.
* **Directories** — Folders for organizing scenarios by topic.
* **Draft/Published** — Draft scenarios are saved but not used by the AI. Publishing makes them active.

## Available Endpoints

<CardGroup>
  <Card title="List Trainings" icon="list" href="./get_all">
    Retrieve all training scenarios
  </Card>

  <Card title="Get Training" icon="magnifying-glass" href="./get">
    Get a single training by ID
  </Card>

  <Card title="Create Training" icon="plus" href="./create">
    Create a new training scenario
  </Card>

  <Card title="Update Training" icon="pen" href="./update">
    Update an existing training
  </Card>

  <Card title="Delete Training" icon="trash" href="./delete">
    Delete a training scenario
  </Card>

  <Card title="Toggle Draft" icon="toggle-on" href="./toggle_draft">
    Publish or unpublish a training
  </Card>

  <Card title="Move to Directory" icon="folder-arrow-down" href="./move">
    Move a training into a directory
  </Card>

  <Card title="Search" icon="magnifying-glass" href="./search">
    Semantic search across training and knowledge base
  </Card>

  <Card title="Generate Scenario" icon="wand-magic-sparkles" href="./generate_scenario">
    Generate a scenario title from a chat session
  </Card>
</CardGroup>

## Best Practices

* Use `search` before creating to avoid duplicates
* Start with draft scenarios, review, then publish
* Use behavioral type for tone and guardrails, scenario-specific for Q\&A
* Organize related scenarios into directories
* Restrict to channels/segments when a scenario only applies to specific contexts
* Use `generate_training_from_session` to learn from real conversations


# List training directories
Source: https://docs.open.cx/api-reference/training/list_directories

get /training/directories
List training directories — List all directories used to organize trainings. Use when pushing training scenarios or knowledge into the AI training index from an external pipeline.



# Move a training to a directory
Source: https://docs.open.cx/api-reference/training/move

post /training/{id}/move
Move a training into a directory, or set directory_id to null to uncategorize it.



# Semantic search across training and knowledge base
Source: https://docs.open.cx/api-reference/training/search

post /training/search
Search across all training scenarios and knowledge base items using natural language.



# Toggle draft status
Source: https://docs.open.cx/api-reference/training/toggle_draft

put /training/{id}/draft
Toggle draft status — Publish or unpublish a training. Use when pushing training scenarios or knowledge into the AI training index from an external pipeline.



# Update a training
Source: https://docs.open.cx/api-reference/training/update

put /training/{id}
Update an existing training. Use when pushing training scenarios or knowledge into the AI training index from an external pipeline.



# Update a training directory
Source: https://docs.open.cx/api-reference/training/update_directory

put /training/directories/{directory_id}
Update a training directory — Rename a training directory. Use when pushing training scenarios or knowledge into the AI training index from an external pipeline.



# Event Types
Source: https://docs.open.cx/api-reference/webhooks/types

Reference for every webhook event OpenCX emits — phone calls, chat sessions, handoffs, CSAT — with payload shapes and delivery guarantees.

## Delivery, signatures & retries

Every event is delivered as an HTTP `POST` with a JSON body using the standard envelope `{ event, organization_id, data }`. Endpoints are managed in **Settings → Webhooks** in the dashboard, which also gives you a self-serve portal with full delivery history, per-attempt response codes, and manual replay.

**Headers.** Each delivery carries three headers:

| Header | Purpose |
| - | - |
| `svix-id` | Unique message ID. **Stable across retries and manual redeliveries** — dedupe on it and your consumer is idempotent. |
| `svix-timestamp` | Delivery timestamp (Unix seconds). Reject deliveries older than your tolerance window to prevent replay. |
| `svix-signature` | HMAC-SHA256 signature of `{id}.{timestamp}.{payload}` using your per-endpoint signing secret (`whsec_…`). |

**Signature verification.** Every endpoint has its own signing secret, available from the webhooks portal. Verify the signature on every delivery before trusting the payload; reject anything that fails verification or falls outside your timestamp tolerance.

**Retries.** A delivery is considered failed on any non-2xx response or timeout. Failed deliveries are retried automatically with exponential backoff over several hours; after the automatic schedule is exhausted, manual replay remains available from the portal. Return a 2xx as fast as possible — enqueue the event and process it asynchronously rather than doing work inline.

**Idempotency.** Dedupe on the `svix-id` header. Phone-call events additionally carry a producer-side idempotency key of the form `<event_type>.<session_id>` — each phone event type fires at most once per session.

`conversation.started` suppresses duplicate publication attempts for the same organization and session for three days. Delivery retries can still reach your endpoint more than once; dedupe using the header above.

**Ordering is not guaranteed.** Retries mean events can arrive out of order; use the `timestamp` field in the payload, not arrival order.

***

`conversation.started`

This event is triggered when a new live session is created, regardless of the channel. It does not wait for a contact message. Historical import jobs do not emit it, and later messages or reopening an existing session do not emit it again.

`first_message` contains the first stored message available at creation, or an empty string (`""`) if none exists yet. `timestamp` is the session creation time. `channel` identifies the session's actual channel; phone sessions use `phone_voice`.

```typescript theme={"dark"}
{
  event: 'conversation.started';
  organization_id: string;
  data: {
    conversation_id: string;
    assignee:
    | {
      type: 'AI';
      name: string;
    }
    | {
      id: string;
      type: 'human';
      name: string;
      avatar_url: string;
    };
    contact: {
      id?: string;
      name?: string;
      enriched_data?: {
        address?: string | null;
        phone_number?: string;
        email?: string;
      };
      custom_data?: object;
    };
    channel:
      | 'web' | 'email' | 'phone_voice' | 'web_voice'
      | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger'
      | 'api' | 'twitter' | 'twitter_mentions' | 'app_review' | 'internal';
    first_message: string;
    timestamp: string;
  };
}
```

***

`conversation.closed`

This event is triggered when a conversation is closed, a conversation can be marked as resolved or not resolved, and can be closed by a human or an AI.

`closed_by` identifies what triggered the close, while `assignee` identifies who the conversation was assigned to at close time. They are independent: a workflow or AI close on a conversation assigned to a human agent still carries that agent's details in `assignee`, so you can attribute the resolution to the assigned agent even when they didn't close it themselves.

```typescript theme={"dark"}
{
    event: "conversation.closed";
    organization_id: string;
    data: {
        conversation_id?: string;
        timestamp: string;
        contact_id?: string;
        contact?: {
          id: string;
          name?: string;
          email?: string;
          phone_number?: string;
          custom_data?: object;
        };
        human_resolution_status: "resolved" | "not_resolved" | null;
        ai_resolution_status: string | null;
        ai_billing_tier: string | null;
        closed_by:
        | {
            type: "AI";
            name: string;
        }
        | {
            id: number;
            type: "human";
            email: string;
        }
        | {
            type: "workflow";
            id: string;
            workflow_run_id: string;
        }
        | {
            type: "contact";
            id: string;
        };
        // Who the conversation was assigned to when it was closed.
        // `alias` / `alias_avatar_url` carry the agent's per-org masked
        // identity when one is configured, null otherwise.
        assignee:
        | {
            type: "AI";
            name: string;
        }
        | {
            type: "human";
            name: string;
            email: string;
            avatar_url: string;
            alias: string | null;
            alias_avatar_url: string | null;
        }
        | {
            type: "unassigned";
        };
        is_from_third_party: boolean;
        third_party_name: "dynamics365" | "freshchat" | "freshdesk" | "gorgias" | "hubspot" | "intercom" | "open" | "salesforce" | "twilio_flex" | "zendesk" | "zendesk_v2" | null;
        summary: string | null | undefined;
        contact_reason: string | null | undefined;
        user_sentiment: string | null | undefined;
        language: string | null | undefined;
    }[];
}
```

***

`conversation.handoff_to_human`

This event is triggered when a conversation is handed off to a human agent. Note that a handoff event can happen for multiple reasons; for example, a human agent might decide to take over the conversation, or the AI might decide to hand off the conversation to a human agent.

```typescript theme={"dark"}
{
    event: "conversation.handoff_to_human";
    organization_id: string;
    data: {
        conversation_id: string | null | undefined;
        timestamp: string;
        contact?: {
          id: string;
          name?: string;
          email?: string;
          phone_number?: string;
          custom_data?: object;
        };
        reason:
        | "ai_decided_to_handoff_the_conversation"
        | "ai_is_forbidden_from_handling_this_topic"
        | "human_agent_decided_to_take_over"
        | "human_agent_decided_forced_handoff"
        | "ai_decided_to_auto_handoff_the_issue";
        summary: string;
        contact_reason?: string;
        user_sentiment?: string;
        was_handedoff_to_third_party?: boolean;
        during_work_hours?: boolean;
        third_party_name?: "dynamics365" | "freshchat" | "freshdesk" | "gorgias" | "hubspot" | "intercom" | "open" | "salesforce" | "twilio_flex" | "zendesk" | "zendesk_v2" | null;
        message_count: number;
        language: string;
        integration_metadata?: {
           sunshine?: {
             sunshine_conversation_id: string;
           };
        };
    }[];
}
```

`conversation.contact_response`

When a contact sends a message to your inbox.

```typescript theme={"dark"}
{
  event: 'conversation.contact_response';
  organization_id: string;
  data: {
    conversation_id: string;
    timestamp: string;
    response: string;
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
    custom_data?: Record<string, unknown> | null | undefined;
  }
}
```

`conversation.ai_response`

When an AI responds to a contact message,

```typescript theme={"dark"}
{
  event: 'conversation.ai_response';
  organization_id: string;
  data: {
    conversation_id: string;
    timestamp: string;
    response: string;
    contact: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
  }
}
```

***

`conversation.agent_response`

When a human agent responds from the Open inbox,

```typescript theme={"dark"}
{
  event: 'conversation.agent_response';
  organization_id: string;
  data: {
    conversation_id: string;
    // The reply's message id — what an option tap is reported against.
    message_id: string;
    timestamp: string;
    customer_id?: string;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    response: string;
    // Present when the reply came from a macro with options, on channels
    // that render them (WhatsApp, Messenger, Instagram, API). On API sessions,
    // render them and report a tap with Send a message's `option_reply`.
    options?: Array<{
      id: string;
      label: string;
      type: 'text' | 'workflow';
    }>;
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
    assignee:
    | {
      type: 'AI';
      name: string;
    }
    | {
      type: 'human';
      name: string;
      email: string;
      avatar_url: string;
      // Per-org agent alias, when one is set. Use these to surface a masked
      // identity instead of the agent's real `name`/`avatar_url`. Always
      // present; both are `null` when the agent has no alias in this org.
      alias: string | null;
      alias_avatar_url: string | null;
    }
    | {
      type: 'unassigned';
    };
  }
}
```

`conversation.third_party_agent_response`

When a third-party software agent responds to a previously handed-off conversation, Open will notify you. In some configurations, Open might also initiate the handoff to a third-party agent, such as Zendesk or Intercom. Even while the third-party agent handles the conversation, Open continues to monitor and send events to your webhooks.

```typescript theme={"dark"}
{
  event: 'conversation.third_party_agent_response';
  organization_id: string;
  data: {
    conversation_id: string | null | undefined;
    timestamp: string;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    third_party_name: 'dynamics365' | 'freshchat' | 'freshdesk' | 'gorgias' | 'hubspot' | 'intercom' | 'open' | 'salesforce' | 'twilio_flex' | 'zendesk' | 'zendesk_v2';
    response: string;
    message_count: number;
    language: string;
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
    agent: {
      name?: string;
    };
    attachments?: Array<{ mime_type: string; url: string; file_name?: string }>;
  }
}
```

***

`conversation.handoff_to_third_party_failed`

Triggered when a handoff to a third-party platform (e.g. Zendesk, Intercom) fails.

```typescript theme={"dark"}
{
  event: 'conversation.handoff_to_third_party_failed';
  organization_id: string;
  data: {
    conversation_id: string;
    timestamp: string;
    third_party_name: 'dynamics365' | 'freshchat' | 'freshdesk' | 'gorgias' | 'hubspot' | 'intercom' | 'open' | 'salesforce' | 'twilio_flex' | 'zendesk' | 'zendesk_v2';
    error: string;
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
    language: string | null;
    custom_data?: object | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
  }
}
```

***

`workflow.run.succeeded`

Triggered when a workflow run completes successfully.

```typescript theme={"dark"}
{
  event: 'workflow.run.succeeded';
  organization_id: string;
  data: {
    run_id: string;
    workflow_id: string;
    trigger_cause: 'automatic' | 'manual' | 'scheduled';
    triggered_by: number | null;
    is_test_run: boolean;
  }
}
```

***

`workflow.run.failed`

Triggered when a workflow run fails.

```typescript theme={"dark"}
{
  event: 'workflow.run.failed';
  organization_id: string;
  data: {
    run_id: string;
    workflow_id: string;
    workflow_name: string;
    session_id: string | null;
    trigger_cause: 'automatic' | 'manual' | 'scheduled';
    triggered_by: number | null;
    is_test_run: boolean;
    error: {
      message: string;
      name: string;
    };
  }
}
```

***

`workflow.dispatch_failed`

Triggered when a phone call could not hand one of its lifecycle stages to the workflow engine at all — so the workflows listening on those triggers never ran, and no `workflow.run.failed` can follow (there is no run). This is the only signal for that failure mode; a stage whose workflows did run but failed produces `workflow.run.failed` instead, never both.

| Field | Description |
| - | - |
| `stage` | Which point in the call failed to dispatch: `call_started`, `pre_transfer`, `post_transfer`, `pre_call_finished`, `call_finished`, or `workflow_tool` (an AI-triggered workflow the agent invoked mid-call). |
| `trigger_types` | The workflow trigger types that would have fired at that stage (e.g. `["phone-call-finished"]`). |
| `error` | Why the dispatch failed, in plain text. |

```typescript theme={"dark"}
{
  event: 'workflow.dispatch_failed';
  organization_id: string;
  data: {
    session_id: string;
    stage: 'call_started' | 'pre_transfer' | 'post_transfer' | 'pre_call_finished' | 'call_finished' | 'workflow_tool';
    trigger_types: string[];
    error: string;
    timestamp: string;
  }
}
```

***

`csat.requested`

Triggered when a CSAT survey is sent to a contact (via email, SMS, WhatsApp, Slack, or shown in the web widget).

```typescript theme={"dark"}
{
  event: 'csat.requested';
  organization_id: string;
  data: {
    session_id: string;
    contact_id: string | null;
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
    delivery_method: string;
    timestamp: string;
  }
}
```

***

`csat.score_submitted`

Triggered when a customer submits or updates a CSAT score for a conversation.

```typescript theme={"dark"}
{
  event: 'csat.score_submitted';
  organization_id: string;
  data: {
    csat_id: string;
    session_id: string;
    contact_id: string | null;
    score: number; // 1–5
    comment: string | null;
    channel: string;
    timestamp: string;
  }
}
```

***

## Phone Call Events

These events are fired for phone calls — both calls handled by AI phone agents and human-only direct-ring calls (see `is_human_call`). They apply to both inbound and outbound calls. `conversation.started` fires when the phone session is created; `phone_call.started` fires when the call starts. Additional calls on an existing session do not emit another `conversation.started`. Phone calls do **not** emit `conversation.closed` — its session message fields (`closed_by`, `is_from_third_party`, `contact_reason`, …) don't map cleanly to a phone interaction. Listen on `phone_call.ended` instead, which carries the equivalent resolution and context fields below.

***

`phone_call.started`

Triggered when a phone call is initiated — either an inbound call is received or an outbound call is placed.
The session's `conversation.started` event is emitted separately at session creation.

```typescript theme={"dark"}
{
  event: 'phone_call.started';
  organization_id: string;
  data: {
    session_id: string;
    phone_agent_id: string | null;   // null for human-only (direct-ring) calls
    phone_agent_name: string | null; // null for human-only (direct-ring) calls
    is_human_call: boolean;          // true when no AI agent was on the call
    direction: 'inbound' | 'outbound';
    from_phone_number: string | null;
    to_phone_number: string | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    timestamp: string;
  }
}
```

***

`phone_call.answered`

Triggered when the remote party picks up the call (SIP participant joined).

```typescript theme={"dark"}
{
  event: 'phone_call.answered';
  organization_id: string;
  data: {
    session_id: string;
    phone_agent_id: string | null;   // null for human-only (direct-ring) calls
    phone_agent_name: string | null; // null for human-only (direct-ring) calls
    is_human_call: boolean;          // true when no AI agent was on the call
    direction: 'inbound' | 'outbound';
    from_phone_number: string | null;
    to_phone_number: string | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    timestamp: string;
  }
}
```

***

### Phone call ended

`phone_call.ended`

Triggered when a phone call ends. This event carries all end-of-call context — resolution status, who hung up, the resolved contact, the agent's configured languages, the call summary, and the session's `custom_data` (SIP X-headers + call metadata) — so listeners do not need a separate `conversation.closed` event for phone calls.

For AI calls using the post-call workflow path, this event is sent **after** `Call Finished` workflows finish, so their updates to session custom data can be included. Timing and available fields vary by calling path; do not assume that every human-call event runs those workflows or contains a final summary. See [Call lifecycle and outcomes](/phone/call-outcomes).

| Field | Description |
| - | - |
| `call_id` | The call record ID, when available. |
| `disposition` | Detailed result when available: `human_answered`, `no_answer`, `busy`, `declined`, `voicemail`, `failed`, `canceled`, or `unknown`. Use this to distinguish results grouped under `unanswered`. |
| `call_ended_by` | Who hung up: `user` (contact), `agent` (AI agent, including transfers), `system` (e.g. inactivity timeout), or `null` when unknown (e.g. outbound calls that never connected). |
| `ai_resolution_status` | Mirrors the persisted `chat_sessions.ai_closure_type`: `resolved` for completed calls, `handed_off` for transfers, or `null` for unanswered/failed calls. |
| `human_resolution_status` | Always `null` for phone calls — there is no human-resolve path on a call. |
| `contact_id` | The resolved contact's id, or `null` if no contact was matched. |
| `contact` | Full contact record (id, name, email, phone, custom\_data) when `contact_id` is set. |
| `language` | The phone agent's configured language list (e.g. `["en"]`, `["es","en"]`), or `null` if no agent is attached. |
| `summary` | The summary stored on the session when the event is sent. It can be missing, empty, or preliminary if no final summary is available. |
| `custom_data` | The session's `custom_data` jsonb after the post-call workflows: incoming SIP X-headers (with the `X-` prefix stripped), values from the `X-OPENCX-SESSION-CUSTOM-DATA` header, call metadata (`duration_seconds`, `participant_count`, `is_outbound`, `recording_available`, `agent_version`, `call_status`, optional `knowledge_snapshot`), plus whatever the `Call Finished` workflows merged in. |

When `custom_data.knowledge_snapshot` is present, scoped snapshots include `instruction_scope`, `knowledge_scope`, and `captured_at`. For compatibility, the call-ended webhook also supplies top-level `instruction_ids` and `directory_ids` arrays inside the snapshot, defaulting missing arrays to `[]`. Existing legacy arrays retain their values. These empty compatibility arrays do not mean the agent had no instructions; read the scope fields for configured selections. A scope with `mode: "all"` can have empty selection arrays. Scope selections do not identify which instructions were used during the call.

```typescript theme={"dark"}
{
  event: 'phone_call.ended';
  organization_id: string;
  data: {
    session_id: string;
    phone_agent_id: string | null;   // null for human-only (direct-ring) calls
    phone_agent_name: string | null; // null for human-only (direct-ring) calls
    is_human_call: boolean;          // true when no AI agent was on the call
    direction: 'inbound' | 'outbound';
    from_phone_number: string | null;
    to_phone_number: string | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    timestamp: string;
    duration_seconds: number | null;
    outcome: 'completed' | 'unanswered' | 'transferred' | 'failed';
    call_id?: string;
    disposition?: 'human_answered' | 'no_answer' | 'busy' | 'declined' | 'voicemail' | 'failed' | 'canceled' | 'unknown';
    recording_url: string | null;
    summary: string | null;
    call_ended_by: 'user' | 'agent' | 'system' | null;
    ai_resolution_status: 'resolved' | 'handed_off' | 'assumed_resolved' | null;
    human_resolution_status: null;
    contact_id: string | null;
    language: string[] | null;
    custom_data: object | null;
  }
}
```

***

`phone_call.transferred`

Triggered when the AI agent transfers a call to another destination (phone number, SIP URI, or graceful hangup).

```typescript theme={"dark"}
{
  event: 'phone_call.transferred';
  organization_id: string;
  data: {
    session_id: string;
    phone_agent_id: string | null;   // null for human-only (direct-ring) calls
    phone_agent_name: string | null; // null for human-only (direct-ring) calls
    is_human_call: boolean;          // true when no AI agent was on the call
    direction: 'inbound' | 'outbound';
    from_phone_number: string | null;
    to_phone_number: string | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    timestamp: string;
    destination: {
      id: string;
      name: string;
      type: 'phone' | 'sip' | 'team' | 'hangup';
    };
    reason: string | null;
    // Present only when the transfer was triggered by the platform's automatic
    // failover on a non-recoverable mid-call error. Branch on presence only.
    failover?: {
      reason: 'provider_failure';
    };
  }
}
```

***

`phone_call.failed`

Triggered when a phone call fails to connect. The `failure_category` field indicates the type of failure.

| Category | Description |
| - | - |
| `no_answer` | Contact didn't pick up |
| `rejected` | Call was actively rejected |
| `busy` | Line was busy |
| `trunk_error` | SIP trunk failure |
| `failed` | Generic failure (timeout, SIP error, etc.) |

```typescript theme={"dark"}
{
  event: 'phone_call.failed';
  organization_id: string;
  data: {
    session_id: string;
    phone_agent_id: string | null;   // null for human-only (direct-ring) calls
    phone_agent_name: string | null; // null for human-only (direct-ring) calls
    is_human_call: boolean;          // true when no AI agent was on the call
    direction: 'inbound' | 'outbound';
    from_phone_number: string | null;
    to_phone_number: string | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    timestamp: string;
    failure_reason: string;
    failure_category: 'no_answer' | 'rejected' | 'busy' | 'trunk_error' | 'failed';
  }
}
```

## Email events

Email events cover broadcasts, sequences, session emails, and organization notifications sent through the existing tracked email paths from your verified sending domains. Each event is delivered only to webhook endpoints belonging to the sending organization. Configure subscriptions in **Settings → Webhooks**.

| Event | When it occurs |
| - | - |
| `email.sent` | The email was sent; recipient-server delivery is not yet confirmed. |
| `email.delivered` | The recipient's mail server accepted the email. |
| `email.delivery_delayed` | Delivery was temporarily delayed. |
| `email.opened` | An email open was detected. Requires open tracking on the sending domain. |
| `email.clicked` | A tracked link was clicked. Requires click tracking on the sending domain. |
| `email.bounced` | The email bounced as undeliverable. |
| `email.complained` | The recipient reported the email as spam. |
| `email.failed` | The email failed to send. |
| `email.suppressed` | A suppression rule blocked sending. |
| `email.scheduled` | The email was scheduled for future sending. |

Only opens and clicks require their respective tracking settings. Subscribing to events does not enable tracking. An open detection is not proof that a person read the email. Events describe newly reported activity; subscribing does not replay historical events. Untagged emails and mail sent through other delivery integrations are outside this event stream.

All 10 events use the same payload:

```typescript theme={"dark"}
{
  event: 'email.clicked'; // One of the 10 event names above.
  organization_id: string;
  data: {
    email_id: string; // OpenCX tracking ID shared by events for this email.
    timestamp: string; // ISO 8601 time when the event occurred.
    from: string; // Sender email address.
    to: string[]; // Recipients reported for the email.
    subject: string;
    source: 'broadcast' | 'sequence' | 'session' | 'notification';
    source_id?: string; // Source reference when available; interpret with source.
    click_url?: string; // HTTP(S) URL, present only for a valid clicked link.
  };
}
```

Email bodies, attachments, device information, and internal routing metadata are not included. Delivery retries of the same incoming event use a stable idempotency key; separate opens and clicks remain separate events. Consumers should still deduplicate deliveries using the `svix-id` header and use `data.timestamp` because events may arrive out of order.


# Send a WhatsApp template
Source: https://docs.open.cx/api-reference/whatsapp/send-template

post /whatsapp/send-template
Directly send a WhatsApp template to a contact. Use when sending WhatsApp messages that require template approval or driving WhatsApp operations from automation.



# Authenticate a widget user
Source: https://docs.open.cx/api-reference/widget/authenticate-contact

post /widget/authenticate-user
Authenticate a widget user — authenticate the contacts. Use when authenticating widget visitors against your own identity provider.



# [Beta] Activate a workflow
Source: https://docs.open.cx/api-reference/workflows/activate

post /workflows/{workflow_id}/activate
Activate the latest version of a workflow. Use when managing deterministic workflow definitions and triggering or inspecting their runs.



# [Beta] Create a workflow
Source: https://docs.open.cx/api-reference/workflows/create

post /workflows
[Beta] Create a workflow. Use when managing deterministic workflow definitions and triggering or inspecting their runs.



# [Beta] Deactivate a workflow
Source: https://docs.open.cx/api-reference/workflows/deactivate

post /workflows/{workflow_id}/deactivate
Deactivate the currently active version of a workflow. Use when managing deterministic workflow definitions and triggering or inspecting their runs.



# [Beta] List available action and trigger types
Source: https://docs.open.cx/api-reference/workflows/definitions

get /workflows/definitions
List all available workflow action types and trigger types with their metadata. Use when managing deterministic workflow definitions and triggering or inspecting their runs.

## Monitor session volume

**Monitor Session Volume** (`monitor-session-volume`) counts sessions created in a
rolling window. It returns the total and links to a small sample. Add conditions,
notifications, or other actions after it to build the behavior you need.

The node is available only in workflows with a **Cron Trigger** whose scheduled
runs are at least **five minutes apart** (for example, `*/5 * * * *`). Faster
schedules are rejected at activation and execution, including for nested monitor
nodes and schedules with a run limit of one. Other workflow triggers cannot
activate or execute it. You can manually test a workflow whose
saved trigger is cron. If the node is absent, it is not available on your deployment yet.

### Configure the node

1. Create a cron workflow that runs every five minutes or less frequently.
2. Add **Monitor Session Volume** and set **Window (minutes)** to a whole number
   from `1` to `120`. The default is `120` (two hours).
3. Optionally set **Tag** to an exact tag name. Leave it empty to count all eligible
   sessions. For example, a classification workflow could tag access reports,
   while this workflow counts sessions with that tag.
4. Add any downstream logic you need. For “more than eight sessions,” use an
   **If/Else** condition checking whether `{{volume.count}}` is greater than `8`,
   where `volume` is the monitor node ID. Add notification actions in that branch.

The monitor has only two inputs: `windowMinutes` and optional `tag`. It has no
threshold, reset timer, update interval, category grouping, source-date override,
incident tracking, or notification destination. Tests of the monitor send nothing;
notification actions added afterward can send real messages during workflow tests.

### Outputs

| Output | Meaning |
| - | - |
| `count` | Total matching sessions in the window. This is not limited to the sample size. |
| `windowStart` | Exclusive start of the evaluated window in ISO 8601 UTC. |
| `windowEnd` | Inclusive end of the evaluated window in ISO 8601 UTC. |
| `sampleSessions` | Up to ten newest matches, each with `id`, optional `number`, `createdAt`, and `url`. |

Every execution reads current reporting data. Repeated or concurrent executions do
not suppress one another. Add threshold checks, duplicate prevention, notification
frequency controls, and delivery retries in downstream workflow steps as needed.
A condition that remains true can therefore run its notification branch on every
scheduled execution.

### Counting behavior

The window is `(now - window, now]`, using Open session creation time. Resolved
sessions still count. Each session counts once, independent of its source channel
or external system. Imports are measured from when the Open session was created;
use an appropriate tag if historical imports should be excluded.

Spam and test billing exclusions, the `Spam/Junk` and `companion-test` tags,
internal sessions, and child sessions are excluded. Counts are organization-scoped.
Reporting data can lag newly created or updated sessions and tags. A successful
query does not guarantee that every recent change has arrived. Query errors fail
the workflow rather than returning zero or a partial count.

### Updating an earlier draft

Remove the old threshold, reset/update timing, category, and source-creation inputs.
Replace `shouldAlert` or `thresholdReached` conditions with comparisons against
`count`. Incident IDs, category counts, and busy flags are no longer returned.
Earlier Slack-specific drafts must also move their message configuration into a
separate notification node. Review notification frequency before activating an
existing draft, because the monitor no longer throttles it.

## Snooze a session

**Snooze Session** (`snooze-session`) is available when native OpenCX ticketing and
**Settings → Workspace → Enable session snoozing** are enabled. The definitions
endpoint omits this action when it is unavailable.

Set `ticketNumber` to a session number in the current organization and
`durationMinutes` to a finite number of at least `1`. The output `snoozedUntil` is
the scheduled wake-up time in ISO 8601 UTC. Duration is measured from step
execution; the workflow continues immediately after applying Snooze.

The session must be open and human-assigned or unassigned, with no active call.
The setting is checked again at execution, so disabling it also blocks already
saved workflows from snoozing sessions. See [session snoozing](/inbox/intro#snooze-a-session)
for wake-up, capacity, and SLA behavior.

The workflow editor provides duration presets and a custom minutes input; stored
`durationMinutes` values and numeric references remain compatible. Workflow session
payloads report `ticketStatus: "snooze"` while a session is snoozed. Session Updated
emits a `status` change on entering or leaving Snooze, including the previous and
new status values. A deadline change alone does not emit another status change.


# [Beta] Delete a workflow
Source: https://docs.open.cx/api-reference/workflows/delete

delete /workflows/{workflow_id}
Soft-delete a workflow and all its versions. Use when managing deterministic workflow definitions and triggering or inspecting their runs.



# [Beta] Get a workflow
Source: https://docs.open.cx/api-reference/workflows/get

get /workflows/{workflow_id}
Get a specific workflow by its UUID, including its blocks, trigger configuration, and active status.



# [Beta] Get a workflow run
Source: https://docs.open.cx/api-reference/workflows/get_run

get /workflows/{workflow_id}/runs/{run_id}
Get details of a specific workflow run, including status, duration, trigger info, and timestamps.



# Workflows (Beta)
Source: https://docs.open.cx/api-reference/workflows/index

The Workflows API lets you programmatically create, manage, and trigger automated workflows.

<Note>The Workflows API is currently in **beta**. Endpoints may change without notice.</Note>

The Workflows API lets you programmatically create, manage, and trigger automated workflows. Workflows are multi-step automations that run in response to events, schedules, webhooks, or manual triggers.

## Key Concepts

* **Workflow** — A named automation with a trigger type and one or more versions
* **Version** — Each edit creates a new version; only one version is active at a time
* **Run** — A single execution of a workflow, with status tracking and duration
* **Trigger type** — What starts the workflow: manual, AI-triggered, cron, webhook, form, or event-based
* **Action type** — A step in the workflow (e.g. `ask-ai`, `send-webhook`, `tag-ticket`)
* **Block** — A control-flow structure (`if-else`, `switch`) that branches execution

## Workflow Lifecycle

1. **Discover** available action and trigger types via the definitions endpoint
2. **Validate** your workflow blocks before creating
3. **Create** a workflow (saved as inactive draft)
4. **Activate** to make the workflow live
5. **Trigger** manually or let it fire automatically based on its trigger type
6. **Monitor** runs and their statuses

## Replies with quick reply suggestions

The `outbound-reply-to-ticket` action accepts an optional `quickReplySuggestions` array of plain-text labels, for example `["Track transfer", "Cancel transfer", "Speak to someone"]`. Omit it or pass `[]` to send the existing reply without buttons. Discover the action and its input schema through [Definitions](./definitions), then [validate](./validate) the workflow before activating it.

Use at most **3 unique, non-empty labels**, each up to **20 characters**. A selection becomes a normal customer reply; it does not pause or branch the sending workflow. Suggestions support the OpenCX web widget, directly connected WhatsApp, Messenger and Instagram channels, and API clients that render message options. Unsupported delivery paths fail the step instead of silently dropping the suggestions.

On WhatsApp, the rendered message body is limited to **1,024 characters**, and the customer's **24-hour reply window** must be open. Outside that window, send an approved template. See [workflow quick reply suggestions](/whatsapp/messaging-rules#quick-reply-suggestions-in-workflows) for setup, translation behavior, and channel limits.

## Available Endpoints

<CardGroup>
  <Card title="Definitions" icon="book" href="./definitions">
    List available action and trigger types
  </Card>

  <Card title="Validate" icon="check" href="./validate">
    Validate workflow blocks before creating
  </Card>

  <Card title="Create Workflow" icon="plus" href="./create">
    Create a new workflow
  </Card>

  <Card title="List Workflows" icon="list" href="./list">
    List all workflows
  </Card>

  <Card title="Get Workflow" icon="magnifying-glass" href="./get">
    Get a specific workflow with full details
  </Card>

  <Card title="Update Workflow" icon="pen" href="./update">
    Update a workflow (creates new version)
  </Card>

  <Card title="Delete Workflow" icon="trash" href="./delete">
    Delete a workflow
  </Card>

  <Card title="Activate" icon="play" href="./activate">
    Activate a workflow version
  </Card>

  <Card title="Deactivate" icon="pause" href="./deactivate">
    Deactivate a workflow
  </Card>

  <Card title="Trigger Workflow" icon="bolt" href="./trigger">
    Manually trigger a workflow
  </Card>

  <Card title="List Runs" icon="clock-rotate-left" href="./list_runs">
    List workflow execution runs
  </Card>

  <Card title="Get Run" icon="magnifying-glass" href="./get_run">
    Get a specific run
  </Card>
</CardGroup>


# [Beta] List workflows
Source: https://docs.open.cx/api-reference/workflows/list

get /workflows
List all workflows in your organization (latest version of each). Use when managing deterministic workflow definitions and triggering or inspecting their runs.



# [Beta] List workflow runs
Source: https://docs.open.cx/api-reference/workflows/list_runs

get /workflows/{workflow_id}/runs
List execution runs for a workflow with filtering and pagination. Use when managing deterministic workflow definitions and triggering or inspecting their runs.



# [Beta] Trigger a workflow
Source: https://docs.open.cx/api-reference/workflows/trigger

post /workflows/{workflow_id}/trigger
Manually trigger a workflow. Use when managing deterministic workflow definitions and triggering or inspecting their runs.



# [Beta] Update a workflow (creates a new version)
Source: https://docs.open.cx/api-reference/workflows/update

patch /workflows/{workflow_id}
[Beta] Update a workflow (creates a new version). Use when managing deterministic workflow definitions and triggering or inspecting their runs.



# [Beta] Validate a workflow definition
Source: https://docs.open.cx/api-reference/workflows/validate

post /workflows/validate
[Beta] Validate a workflow definition — Validate workflow blocks without creating a workflow.



# Connect App Store and Google Play reviews
Source: https://docs.open.cx/app-reviews/connect-app-reviews

Connect App Store and Google Play so every new app review opens a session your AI or team can answer. Use when setting up app review replies.

Every new App Store or Google Play review opens a session in the inbox. Your AI or your team
answers it there, and the answer is published on the store as the app's one public developer reply.

Each store is connected on its own, in one of two ways:

| Store | Connect directly | Or through Appfigures |
| - | - | - |
| App Store | Your App Store Connect account | Your Appfigures account |
| Google Play | Your Google Play Console account | Your Appfigures account |

A direct connection needs no extra subscription. Appfigures needs an Appfigures plan that includes
review replies. A store uses one connection at a time.

## Before you start

* You need permission to manage channel settings in OpenCX to connect or change a store.
* In OpenCX, go to **Channels → App Reviews** and choose **Connect** on the store's card. Pick how
  to connect the store, choose **Continue**, then follow that option's setup steps.

## Connect the App Store directly

1. In [App Store Connect](https://appstoreconnect.apple.com/access/integrations/api), open
   **Users and Access → Integrations → App Store Connect API** and generate a **Team key** with the
   **Customer Support** role.
2. Download the key file (`.p8`). Apple lets you download it only once.
3. Copy the **Issuer ID** shown above the list of keys, and the **Key ID** of the new key.
4. Find each app's **Apple ID** under **App Information**.
5. In OpenCX, choose **App Store Connect**, fill in the four fields, and upload or paste the `.p8`
   file. Separate several Apple IDs with commas.

## Connect Google Play directly

1. In Google Cloud, enable the **Google Play Android Developer API** for a project, then create a
   service account and download a **JSON key** for it.
2. In [Play Console](https://play.google.com/console/developers/users-and-permissions), open
   **Users and permissions**, invite the service account's email, and grant it **Reply to reviews**
   for your apps.
3. In OpenCX, choose **Google Play Developer API**, upload or paste the JSON key, and enter the
   package names of your apps (for example `com.example.app`). Separate several with commas.

<Note>
  Google can take several hours to activate a newly invited service account. Until then, replies are
  refused and the reviews stay answerable.
</Note>

## Connect through Appfigures

1. Link your App Store Connect and Google Play Console accounts in Appfigures.
2. Create a personal access token under **Account → API** in Appfigures.
3. In OpenCX, choose **Appfigures** on the store's card and paste the token. The same token serves
   both stores.

## What happens after you connect

* New reviews appear in the inbox within a few minutes. Reviews from the last two days are collected
  when you first connect; a large backlog arrives over the next few checks rather than all at once.
* Reviews that already have a developer reply on the store are skipped.
* The session's side panel is titled with the app and the store, for example `Example Radio · Google
  Play`, and shows the rating, the reviewer's name, and the app version. For direct connections it
  also links to the store: the review itself on Google Play, and the app's reviews on the App Store.
* The reviewer's contact carries the app in the custom data field **app\_review\_app**, so a workflow
  can route or tag reviews by app.
* Google Play only shares reviews that include text. Star-only ratings do not open sessions.

OpenCX checks the credentials when you save. A key it can never use (a wrong file, a missing Apple
ID, a malformed package name) is rejected with a message saying what to fix. For a direct connection,
OpenCX also reads your reviews once with the new key; if the store refuses it, nothing is saved.
This proves the key can read reviews, not that it can reply: a missing reply permission only shows
when the first reply fails, and that review stays answerable once you fix it.

## Name your apps

A review shows the app's identifier until you name the app: the Apple ID, the Google Play package
name, or the Appfigures product ID. To give an app a name your team knows it by, choose **Manage
connection**, then **Name an app**, and enter the identifier and the name. You can add, change or
remove names without entering the credentials again.

A review keeps the name its app had when the review arrived, so renaming an app changes only the
reviews that come after.

## Choose where collection starts

**Collect reviews from** is optional. Reviews submitted before that date never open sessions. If you
are moving a store from another connection, for example from Appfigures to a direct connection,
pick today: collection then starts from the moment you save, so reviews already in your inbox are
not opened a second time. You can change or clear it later from **Manage connection** without
entering the credentials again.

## Replying

A review takes exactly one public developer reply.

| Store | Reply length | Replies per hour |
| - | - | - |
| App Store | No limit | No limit |
| Google Play | 350 characters | About 30 |

The composer counts characters against the store's limit. On the App Store, Apple publishes the
reply after its own review, so it can take a while to appear.

## Pause, switch, or disconnect

* **Pause:** turn off **Open sessions for new reviews** on the store's card. No new sessions open,
  and reviews already in the inbox stay answerable.
* **Update credentials:** choose **Manage connection** to open the current connection's settings and
  enter new credentials.
* **Switch:** disconnect the store, then connect it again, pick the other option, and set **Collect
  reviews from** to today. Reviews that arrived through the old connection can no longer be replied
  to from OpenCX; answer those on the store directly.
* **Disconnect:** deletes the stored credentials. New reviews stop opening sessions, and reviews
  already in the inbox can no longer be replied to.

## Troubleshooting

| Symptom | Fix |
| - | - |
| "The private key must be the full contents of the .p8 file" | Upload the `.p8` file you downloaded from App Store Connect, not a key from elsewhere. |
| "Paste the full JSON key file of the service account" | Paste the whole JSON file Google Cloud gave you, including `client_email` and `private_key`. |
| Google Play replies fail right after connecting | Check the service account has **Reply to reviews** in Play Console, and allow a few hours for a new invite to take effect. |
| No new sessions | Check the store's card shows **Connected**, not **Paused**, that the app IDs or package names are correct, and that **Collect reviews from** is not later than the reviews you expect. |


# Architecture overview
Source: https://docs.open.cx/architecture-overview

How data flows through OpenCX — channels in, AI inference, knowledge base, helpdesk handoff out, and what your team controls along the way.

OpenCX sits between the channels your customers use and the systems your team operates. This page is for admins and security reviewers — what data crosses what boundary, what stays inside OpenCX, and what your team can switch off.

## Data flow at a glance

```mermaid theme={"dark"}
flowchart LR
  A[Customer message] --> B[Channel]
  B --> C[OpenCX]
  C --> D[AI agent]
  D --> E[Knowledge base]
  D --> F[Actions / your APIs]
  C --> G[Your helpdesk]
  C --> H[Your team's inbox]
```

Every message lands in OpenCX first. The AI reads from your knowledge base, optionally calls your APIs, and replies on the same channel. Anything the AI hands off goes to your team — in the [OpenCX inbox](https://platform.open.cx/inbox), your helpdesk, or both.

## Where data lives

**Sessions** are the unit of every conversation — customer messages, AI replies, handoff events, and action calls all attach to one session. Sessions stay inside your OpenCX organization. See [Core concepts](/core-concepts) for the full vocabulary.

**Knowledge** is everything the AI reads from. Articles you author in the [Help Center](/help-center/overview) plus content synced from connected sources (Zendesk, Notion, Confluence, Shopify, websites). Drafts and segment-restricted content stay internal — the AI uses them in agent-facing surfaces only, never in customer replies. See [Agent Training](/knowledge/introduction).

**Identifiers shared with third parties** are the minimum needed to make handoff reversible. When a session hands off to a helpdesk like Zendesk or HubSpot, OpenCX writes the session ID and tags onto the ticket so your team can click back. The full transcript syncs as ticket comments.

## What touches the AI

* The customer's current message and the recent conversation history.
* The relevant knowledge base entries, ranked by similarity.
* Action specs (your API definitions). The AI does not see the data your APIs return until it calls one — and only the response of that call.

## What your team controls

<AccordionGroup>
  <Accordion title="Autopilot" icon="sliders">
    Per-channel switch plus topic gating. Turn the AI off entirely for a channel, or limit it to specific topics (reply to billing questions, hand off login issues). Configure from [Autopilot settings](https://platform.open.cx/settings/autopilot). See [Autopilot topics](/handoff/topics).
  </Accordion>

  <Accordion title="PII redaction" icon="user-shield">
    Opt-in redaction of personal data as customer messages arrive, before storage and inference. Off by default; once you turn it on, emails, phone numbers, card numbers, and other patterns you choose are masked and never reach the AI in raw form. See [PII redaction](/safety/pii-redaction).
  </Accordion>

  <Accordion title="Inspect mode and Debug mode" icon="magnifying-glass">
    Open any session and see exactly what the AI saw — the knowledge entries it ranked, the actions it considered, the prompts it built. Useful for security review and for tuning answers. See [Inspect mode](/safety/inspect-mode).
  </Accordion>

  <Accordion title="SSO and access control" icon="key">
    Let your team sign in through your own identity provider (SAML 2.0 / OIDC) and assign roles per teammate. Restrict who can change Autopilot, view transcripts, or run actions. See [SSO](/security/sso).
  </Accordion>
</AccordionGroup>

## Limits and honest expectations

AI replies typically land within a second or two; under load this can stretch. Knowledge syncs poll on a schedule — typically every few hours, configurable per source. Handoffs to third-party helpdesks are best-effort; if a third-party API is down, OpenCX retries and surfaces the failure as a `conversation.handoff_to_third_party_failed` event.

***

## Related Documentation

<CardGroup>
  <Card title="AI Safety" icon="shield" href="/safety/introduction">
    Inspect mode, debug mode, PII redaction, prohibited topics.
  </Card>

  <Card title="SSO" icon="key" href="/security/sso">
    Sign in through your own identity provider.
  </Card>

  <Card title="Bug bounty" icon="bug" href="/security/bug-bounty">
    Report security issues.
  </Card>

  <Card title="API authentication" icon="code" href="/api-reference/authentication">
    How API keys and scopes work.
  </Card>
</CardGroup>


# Help
Source: https://docs.open.cx/archive/help/coming-soon

In-app support and live chat with the OpenCX team — coming soon.

In-app help and live chat with the OpenCX team are coming soon.

In the meantime, reach us at **[support@open.cx](mailto:support@open.cx)** or open a conversation from your [OpenCX dashboard](https://platform.open.cx).


# Billing projections, invoice history, and payment methods
Source: https://docs.open.cx/billing

Review projected charges, issued invoices and payment balances, the sessions and calls behind each charge, manage payment methods, and find bank-transfer details for your billing organization.

Open **Settings → Billing** to review projected AI resolution and AI voice-minute charges, view invoice history, and manage payment details. Billing read access allows viewing the page and invoice history; listing the sessions behind a charge also requires access to view sessions. Billing write access is required to open the payment portal. Organization admins have all of these.

## Billing organizations

Usage from the main billing organization and its linked organizations is pooled. Each product's monthly included allowance is applied once to its combined usage.

Your agreement can price a group of organizations separately, for example **Consumer Chat**. That group's usage is billed against its own allowance and rates, on its own lines named after the group, and does not count toward the shared allowance. Its charges appear on the same invoices as the rest of the product.

A linked organization displays an alert naming its main billing organization. If you are also a member of that organization with admin or billing access, **Open billing for …** switches you directly to its billing page. Payment details, projected charges, and invoice history are shown only in the main billing organization.

## Understand the projection

The **Next invoice** section groups all configured products by expected invoice date and currency. Products belonging to the same invoice appear together in each monthly table. Each monthly subtotal includes all its line items. Different invoice dates or currencies have separate invoice groups within this section.

AI voice minutes appear only when your main billing organization has an unarchived voice billing line item, including when usage is zero or no AI resolutions plan is configured. Products without billing terms are omitted. Displayed months begin no earlier than your contract's starting month or **September 2026**. All billing dates and month boundaries use UTC.

Each monthly breakdown uses invoice-style rows with a description, quantity, unit price, and amount:

* A flat-fee row with the included AI resolutions or voice minutes.
* Overage rows with excess sessions or minutes, the applicable rates, and projected charges. Tiered pricing shows one row per used tier; volume pricing shows one row at the selected rate.
* The projected total for that month.

A separately priced group of organizations has its own flat-fee and overage rows, with the group's name after each description, such as **AI resolutions — flat fee · Consumer Chat**.

Voice usage sums the recorded billable minutes across all call origins, including test calls. AI participation time is rounded up to whole minutes per call. Usage belongs to the UTC month when its billing record is created, so calls processed later can appear in a later month. Recent calls may take time to appear. The table shows included and excess minutes, without a separate total-usage figure.

Monthly billing shows one month. Quarterly billing shows the calendar quarter's months separately, including scheduled flat fees for future months. Future overage quantities are marked **Not started**. For example, an October 1 monthly invoice is projected from September; an October 1 quarterly invoice covers July–September, with months before September 2026 omitted from this view.

A mid-month service start prorates the first month's flat fee by active calendar days, including the start date. When the configured monthly flat fee is greater than zero, that partial first month has no overage charge. The page explains the proration.

A contract ending mid-month also prorates the final month's flat fee for its service days. The same overage waiver applies when the configured monthly flat fee is greater than zero.

When a product has no flat fee, partial months charge usage above the **full monthly included allowance** at the agreed extra-unit rate. The allowance is not reduced for a partial month. This applies to both AI resolutions and AI voice minutes, including service starting, ending, or being archived mid-month. With no allowance, all usage during the service period counts toward overage. For example, 150 units used with 100 included units and a $2 extra-unit rate costs $100.

<Note>
  These amounts are projections, not final invoices or requests for payment. Every displayed month
  uses current billing settings and eligible recorded rollover. They exclude taxes, other credits,
  and products other than AI resolutions and AI voice minutes. Automatic rollover from a month that
  has not been processed is not yet included; manually set totals apply in their eligible month. Changes to billing settings can change the displayed estimates.
  Opening this page does not generate an invoice or account for which months have already been
  invoiced.
</Note>

**Next invoice expected** shows the anticipated issuance date, not the payment due date. Consult your issued invoice for its final amount and payment deadline.

## Review invoice history

**Invoice history**, below **Next invoice**, shows issued invoices recorded in OpenCX. Drafts and voided invoices are hidden. Invoices not recorded in OpenCX do not appear in this history.

The five most recently issued invoices appear expanded. Select **Load more** to view older invoices, five at a time. Each invoice shows its number, issue date, currency, and due date when available. Monthly tables show the recorded descriptions, quantities, unit prices, and amounts in the same format as the projection. Historical charges do not change when current billing terms change.

Each invoice also shows its subtotal, final total, amount paid, and remaining balance. An unavailable amount appears as **—**, rather than zero. All dates use UTC.

| Status | Meaning |
| - | - |
| **Awaiting payment** | The invoice is open and has not passed its recorded due date, or has no recorded due date. |
| **Overdue** | The invoice is open and its recorded due date has passed. |
| **Paid** | The invoice is recorded as paid. |
| **Unpaid** | An unpaid invoice retained in your history. This does not mean it has been canceled. |

These invoice cards are read-only, with no payment actions. Invoice history remains available even when no current billing terms are configured. If history cannot load, select **Retry**; previously loaded invoices remain visible when loading an older page fails.

## Review billed sessions and calls

Each product in a monthly table, in both **Next invoice** and **Invoice history**, has a link on its flat-fee row: **View billed sessions** for AI resolutions and **View billed calls** for AI voice minutes. It opens a panel listing every billed item behind that month's charge, newest first. A separately priced group has its own link, listing only its organizations' usage; the shared rows list everyone else's.

| Product | One row per | Shows |
| - | - | - |
| AI resolutions | Billed resolution | Session number, billing time, and channel. A voice session resolved on more than one call appears once per call. |
| AI voice minutes | Billed call | Session number, billing time, channel, call origin, duration, and billable minutes rounded up per call. |

The list covers the period the charge bills. For **Next invoice**, that is the month from your contract start until now. For an issued invoice, it is the service period recorded when the invoice was created, so later changes to billing terms do not change it. The panel shows the totals for the period, its start and end times, and when the list was last updated. All times use UTC.

Usage from linked organizations is included, with an **Organization** column when more than one organization has billed usage. Session numbers in your current organization open the session in the inbox. To open a linked organization's session, switch to that organization.

* Filter by organization, channel, or, for voice minutes, call origin. Each option shows its count for the period.
* Search by session number (for example, `#1234`) or session ID. When the session was not billed for that product and month, the panel says so.
* Select **Load more** for older rows, or **Download CSV** to export every row matching the current filters and search.

Recent activity can take a few minutes to appear. When the list holds fewer sessions or minutes than the charge, the panel notes that it is still catching up. When an issued invoice was adjusted after it was created, the panel says so and lists usage as recorded.

The link is unavailable when nothing was billed for that product and month, and hidden for months that have not started. Without access to view sessions, the link is visible but disabled.

## Monthly invoice preparation

Completed service months are prepared for billing on the first of each month at **03:00 UTC**,
starting with September 2026 service. Invoices remain drafts for finance review before issuance;
preparing a draft does not send an invoice or charge a saved card.

Overage quantities are rounded down to whole units before applying the agreed unit price.
For example, 1.5 excess units are billed as 1 unit, and 0.5 excess units produce no overage charge.

Monthly plans are billed for the completed month. Quarterly plans retain separate monthly charges
and are prepared after the calendar quarter closes. If a contract ends or its plan is archived
earlier, its remaining charges are prepared on the next monthly run. Archiving stops service at
the archive timestamp; the existing partial-month rules apply.

Rollover allowance accounting is recorded monthly. When an invoice is created, each uninvoiced
month is calculated from recorded usage using the current billing settings, including product,
currency, flat fee, included units, and overage rate or tier schedule. This also applies to earlier
months on a quarterly invoice. Saving the invoice fixes its pricing and charges. Retrying an interrupted generation uses that saved invoice; later pricing
edits do not alter it. Products can share an invoice when the invoice
date, currency, payment terms, and grace period match; differing terms produce separate invoices.
If a plan is added after a month's invoice has been prepared, its additional charges appear on
a separate draft. Charges already assigned to the original invoice are not repeated.

Separately priced groups follow the same rule: each month not yet invoiced is billed with the
groups and organizations configured when its invoice is created. A group added later starts with
the first month not yet invoiced; earlier invoices keep those organizations at the shared price.
Removing a group bills its organizations at the shared price for every month not yet invoiced.

## Generate or regenerate an invoice

Billing administrators can open an organization's invoices in **Admin → Billing**, then select
**Generate or regenerate invoice**. Choose a completed **Service month (UTC)** from September 2026
onward. **Generate missing invoice** is available when that period has no existing invoice created
here. Use **Regenerate existing invoices** to replace the period's invoices after correcting billing
settings. A paid invoice covering the period prevents regeneration.

Select **Preview drafts** to review every included month, the previous charges and the new totals.
Regeneration recalculates recorded usage using all current billing settings, including newly added
products and tier pricing. It replaces complete billing periods, so a quarterly invoice includes
all its months. Different billing dates, currencies or payment terms can produce multiple drafts.
If corrected settings leave no charges due, the preview shows that no replacement will be created.

Manual edits on the previous invoice are discarded in the replacement; the old invoice and its
edit history remain available. Existing drafts are removed from the billing provider and unpaid
issued invoices are voided before replacement drafts are created. If the provider cannot retire
an invoice, the operation remains incomplete and shows the error. Resolve the payment with the
billing provider, then retry; no replacement is created until retirement succeeds. If an invoice
becomes paid during confirmation, regeneration stops and records the reason in history.

Enter a written **Reason**, then select **Confirm generation** or **Confirm regeneration**.
The new invoices remain drafts. Finalizing and emailing are separate actions, and generation does
not charge a saved card. **Generation history** records the administrator, reason, reviewed charges
and links to previous and replacement invoices. **Retry saved generation** resumes an interrupted
operation using the saved charges, even if settings have changed since confirmation.

<Warning>
  Regeneration does not change recorded rollover balances or later invoices. Review later invoices
  separately when corrected allowance or usage could affect their charges. Duplicate checks cover
  invoices created here; check for invoices created externally before confirming.
</Warning>

## Manage billing line items

Billing administrators open **Admin → Billing → Manage line items** for an organization to view its line items in a sheet.
Choose **Add line item** to open the product-selection sheet above it. Selecting a product opens a third
sheet on top, where you configure its pricing and terms.
Each save creates one line item. Products already configured cannot be selected again.
Before saving, use **Back** or close the top sheet to reveal product selection beneath it. Selecting the same product preserves
entered values; selecting a different product resets the form to its creation defaults.

Editing opens the saved terms in a sheet above the line-item list. The product is fixed after the first successful save;
pricing, allowances, and other terms remain editable. To correct a product selection, archive
the existing item and add a new one. Archiving preserves the original item's saved terms and history.

### Price selected organizations separately

To bill some of the payer's organizations at different terms, select **Add price** under
**Tiered overage pricing** while adding or editing a line item:

1. Enter a **Label**, such as **Consumer Chat**. It appears on invoice lines and on the customer's
   billing page, so use a name the customer recognizes. Each price on a line item needs a different label.
2. Select the **Orgs** it covers: the main billing organization or any of its linked organizations.
   An organization can have only one price per product.
3. Set the **Flat fee** (0 by default), included allowance, and extra-unit rate or tier schedule,
   and choose its rollover option.

Saving the line item saves its prices. Their usage leaves the shared allowance and is billed against
their own allowance and rates. The flat fee is charged in addition to the line item's flat fee.
Currency, contract dates, invoice frequency, payment terms, grace period, and billing emails always
follow the line item, so its prices share its invoices. Each price tracks its own rollover, and
its reset option appears after the price is first saved.

Remove a price with its delete button and save. Its organizations return to the shared price for
every month not yet invoiced. Archiving a line item also archives its prices. The line-item list
shows each price's label, organizations, and terms.

## Tiered overage pricing

AI resolutions and AI voice minutes can each have an independent tier schedule and pricing mode.
Without tiers, the single extra-unit rate applies. Tier thresholds count only excess usage after
included units and eligible rollover are deducted. They reset every UTC calendar month, even when
you receive a quarterly invoice. Partial-month overage waivers still apply.

* **Graduated** is the default. Each portion of excess usage is charged at its tier's rate.
* **Volume** applies the rate of the tier reached to all excess units for that month. Reaching a
  cheaper tier can reduce the total overage charge.

For example, suppose the first 5,000 excess units cost 0.10 each, the next 15,000 cost 0.08 each,
and units above 20,000 cost 0.05 each. At 25,000 excess units, graduated overage is 1,950.00;
volume overage is 1,250.00. Any monthly flat fee is added separately. Each used tier's charge is
rounded to currency cents before the line amounts are summed. A used free tier remains visible
with a zero charge.

Billing administrators configure tiers in **Admin → Billing → Line items**. Enable
**Tiered overage pricing**, choose the pricing mode, and enter each tier's **Through** limit and rate.
The editor derives each start automatically from the included allowance or the previous tier's end.
For example, with 2,000 included units, a tier ending at 5,000 covers units 2,001–5,000;
the next tier starts at 5,001. Ends must increase, and the final tier is unlimited, so there are
no gaps or overlaps. Every finite tier must cover a positive whole number of excess units.
Eligible rollover shifts these ranges without changing their widths: 500 rollover units move
that first range to 2,501–5,500. The editor shows ranges before rollover; monthly charges use the
eligible rollover for that month. Rates can be zero, rise, or fall. Saving changes
updates **Settings → Billing** projections immediately and affects subsequent invoice creation.
Existing invoices keep their saved charges.

## Monthly allowance rollover

Each product has its own rollover option. **To term end** is the default: unused allowance is
recorded month by month, without reducing later usage charges or creating an automatic renewal credit.

With **To next month**, the current month's allowance is used first, followed by unused allowance
from the immediately preceding service month. Older rollover cannot be used again. For example,
with 100 included units and 40 carried units, 150 units used produces 10 excess units. Using 120 units
produces no excess and no new rollover; using 80 units leaves 20 new units for the next month.

Prorated months earn no automatic rollover and retain the fee and overage rules above. Rollover is tracked
separately for each product and billing line. Updating an existing line's end date preserves its
recorded rollover; a reset must be explicitly selected.

Changing rollover mode preserves recorded rollover. **To next month** makes only the immediately
preceding month's rollover eligible; changing back to **To term end** counts all unreset records
again. Amounts voided by earlier mode changes or explicit resets remain voided.
A reset voids that product's recorded balance, including the immediately preceding month, while
retaining its history. Neither a reset nor a mode change alters charges already prepared.

### Manually set a month’s rollover

Staff billing admins can open **Rollover** for an organization in the billing administration
page, then select **Edit rollover** for the product. The editor opens in a separate stacked
sheet. Linked organizations share their payer’s rollover; resolutions and voice minutes are
managed separately.

Choose any past, current, or future source month. The amount is prefilled with that month’s
existing rollover total. Enter the replacement total and a required reason, then select
**Save rollover**. Non-negative decimals are supported, including **0** to clear the month.
The entered amount replaces the total; it is not added to automatically earned rollover.
A manually set total remains authoritative when the source month is processed later.
History retains the old amount, new amount, reason, author, and time of each change.

For **To next month**, January’s total applies only in February, after February’s included
allowance. Any unused portion expires after February. The balance card shows recorded carry
usable in the current UTC month; future entries remain visible in their source month’s history.
For **To term end**, manual totals count toward the recorded balance without reducing monthly
charges. Explicit resets clear both recorded manual and automatic rollover while retaining history.

You can change rollover even if the receiving month’s charges have already been processed.
A warning explains that its invoice may need regeneration. Saving rollover does not regenerate
invoices or change already-prepared charges.

## Manage cards and issued invoices

Select **Manage payments and invoices** to add or update a card and view or pay issued invoices. This action requires billing write access. Subscription changes and cancellation are not available in the payment portal.

The **Saved cards** section shows each card's brand, last four digits, expiration date, and
whether it is the default. Expired cards and missing defaults are shown explicitly. If card
information cannot be loaded, the page shows it as unavailable; this does not mean no card is saved.
Select **Refresh cards** after changing a payment method.

Saving a card does not enable automatic collection or change your agreed payment terms. Your
billing organization has a collection preference, managed by finance. Finance approves collection
for each invoice and can select a different saved card for that invoice without changing your
default card.

When finance approves card collection during finalization, collection starts after approval,
without waiting for a payment-term due date. Failed payments may be retried automatically.
An invoice finalized for manual payment can instead receive a single card-payment attempt after
finance approval; that action does not enable automatic retries. A saved card does not guarantee
payment will succeed, and you may need to authenticate a payment or update the card.

Successful card payments receive an email receipt when email delivery is configured. If a payment
requires your action, follow the payment link in the email. Contact
[cfo@open.cx](mailto:cfo@open.cx) if you need help with an issued invoice.

## Pay by bank transfer

Where supported, the page displays bank-transfer details assigned to your billing organization for each currency used by its unarchived billing line items, including voice-only plans. Missing payment details are prepared automatically when you visit the page. Billing admins also initiate setup when adding line items.

Use the displayed account details and currency. Refer to your issued invoice for the amount to transfer; the projection is not an amount due.

If bank transfer is unavailable for the billing currency or account, contact [cfo@open.cx](mailto:cfo@open.cx) for payment options. If setup temporarily fails, the affected bank-details section is hidden while saved billing terms and available projections remain visible. Select **Retry**, or contact the same address for help.


# Build Agents get started
Source: https://docs.open.cx/build-agents/get-started

Pick the channel your customers reach you on and build an AI agent for it — widget, phone, WhatsApp, email, or SMS.

OpenCX agents run on the channels your customers already use. Pick the channel below and follow its introduction page — each one walks you from zero to a live AI agent on that channel.

## Choose your channel

<CardGroup>
  <Card title="AI Chat Widget" icon="message" href="/widget/introduction">
    Embed an AI chat widget on your website. Fastest path to a working agent.
  </Card>

  <Card title="AI Phone Support" icon="phone" href="/phone/introduction">
    Inbound and outbound AI voice agents with a real phone number.
  </Card>

  <Card title="AI WhatsApp Support" icon="whatsapp" href="/whatsapp/introduction">
    Answer customers on WhatsApp Business — one-to-one and templated outbound.
  </Card>

  <Card title="AI Email Support" icon="envelope" href="/email/introduction">
    Forward support mail to OpenCX and let the agent reply from your domain.
  </Card>

  <Card title="AI SMS Support" icon="comment-sms" href="/sms/introduction">
    Register a number (10DLC or toll-free) and reply to texts automatically.
  </Card>

  <Card title="AI Actions" icon="bolt" href="/actions/introduction">
    Teach agents to call your APIs — lookups, updates, real work on the user's behalf.
  </Card>
</CardGroup>

## What every channel shares

<AccordionGroup>
  <Accordion title="Autopilot" icon="sliders">
    Toggle AI responses on or off per channel. When off, the channel still captures messages and routes them to your human team.
  </Accordion>

  <Accordion title="Knowledge" icon="book">
    Agents answer from your help center articles, training scenarios, and connected knowledge sources. See [Agent Training](/knowledge/introduction).
  </Accordion>

  <Accordion title="Handoff to humans" icon="user-group">
    Agents escalate to your team when they reach a handoff topic, detect frustration, or run out of confidence. See [Handoff](/handoff/introduction).
  </Accordion>

  <Accordion title="Actions" icon="bolt">
    Any channel can call your APIs to look up orders, update records, or trigger workflows. See [AI Actions](/actions/introduction).
  </Accordion>
</AccordionGroup>

<Tip>New to OpenCX? Start with the [AI Chat Widget](/widget/introduction) — it takes \~10 minutes to embed and test on your site.</Tip>

***

## Related Documentation

<CardGroup>
  <Card title="Agent Training" icon="book" href="/knowledge/introduction">
    Train your agent with articles, topics, and connected sources.
  </Card>

  <Card title="AI Actions" icon="bolt" href="/actions/introduction">
    Give agents the ability to call your APIs.
  </Card>

  <Card title="AI Safety" icon="shield" href="/safety/introduction">
    Inspect mode, PII redaction, and prohibited topics.
  </Card>

  <Card title="Integrations" icon="plug" href="/dashboard/introduction">
    Connect helpdesks, CRMs, and other tools.
  </Card>
</CardGroup>


# Changelog
Source: https://docs.open.cx/changelog

Learn about the latest updates to the Open platform

<Update label="October 5, 2026">
  ## Send and set a status

  <Frame>
    <img alt="The reply composer with the Send menu open, listing Send and resolve and three Send and custom status options" />
  </Frame>

  Reply and change the session status in one action. The arrow beside Send now offers Send and resolve plus any custom statuses your workspace enables.

  <Expandable title="Features">
    * Send and resolve: open the arrow beside Send, or press ⌘⇧Enter (Ctrl⇧Enter on Windows and Linux), to send your reply and resolve the session together
    * Send and set a custom status: pick the statuses to offer under Settings → Workspace → Send and set status; each appears as “Send and \[status]” in the same menu
    * Statuses limited to certain teams only appear for agents in those teams
  </Expandable>
</Update>

<Update label="September 28, 2026">
  ## Organize Structured Fields into groups

  <Frame>
    <img alt="Structured Fields settings with QA and Session details groups, each listing its typed fields" />
  </Frame>

  Split your Structured Fields into named sets, such as QA and Session details, and keep related fields together in settings and in the close form.

  <Expandable title="Features">
    * Create groups under Settings → Structured Fields and add fields to them, or move a field from its edit dialog
    * Give a group an optional description, shown when you hover the icon next to its name
    * The close form and the close requirements picker list fields under their group
    * Groups and each field’s group are available in the public API and the MCP tools
  </Expandable>

  <Expandable title="Improvements">
    * “Show when” lists only fields from the same group, so dependent fields stay together
    * The “Show when” picker is now as wide as its value, like the other pickers in the field dialog
  </Expandable>
</Update>

<Update label="September 28, 2026">
  ## Connect App Store and Google Play directly

  <Frame>
    <img alt="Google Play connection settings with setup steps, a service account key field and package names" />
  </Frame>

  Answer app reviews from the inbox by connecting your own App Store Connect and Google Play Console accounts, with no extra subscription.

  <Expandable title="Features">
    * Connect the App Store with an App Store Connect API key, and Google Play with a service account that can reply to reviews
    * Each store is connected on its own, and can cover several apps
    * Choose a date to start collecting from, so reviews already in your inbox are not opened twice when you change how a store is connected
    * The review card in a session links to the store: to the review itself on Google Play, and to the app’s reviews on the App Store
  </Expandable>

  <Expandable title="Improvements">
    * Connecting a store is two steps: pick how to connect, then follow that option’s setup steps
    * Keys are checked when you save: a key or app the store cannot read reviews for is refused with a message saying what to fix
    * Key files can be uploaded, and stay hidden once added
  </Expandable>
</Update>

<Update label="September 25, 2026">
  ## Help Center: who changed what

  Every saved version now names who saved it and who published it, and article and topic changes appear in the audit log. Topics gained a quicker Edit action and a searchable Move to menu.

  <Expandable title="Features">
    * Icons in articles: place an image in the text at text height, and turn it back into a figure; an emoji name typed between colons becomes the emoji
    * Align an image left, centre or right; replace an image in place, keeping its size and alt text
    * Version history shows who saved each version, when, and who took the live one live; API writes name the API key and automatic translations are marked as such
    * Creating, editing, publishing, unpublishing, deleting and restoring an article or a topic is recorded in the organization audit log
    * The version history API returns created\_by and published\_by for every version
  </Expandable>

  <Expandable title="Improvements">
    * Rename and Icon & description are one Edit action on a topic
    * Move to… lists the topics in a searchable submenu and confirms with a check mark before it closes
    * Version history shows the full date with the year
    * Opening an article from the tree no longer flashes a placeholder on a short load
  </Expandable>

  <Expandable title="Fixes">
    * Tighter spacing inside callouts and the reference-label popover in the editor
  </Expandable>
</Update>

<Update label="September 24, 2026">
  ## A focused desk for phone agents

  <Frame>
    <img alt="Phone Desk with the availability control in the header and a centered dialer ready to call from the Support line" />
  </Frame>

  Give phone agents a simpler inbox with a centered dialer, quick availability controls and the session details they already use.

  <Expandable title="Features">
    * Phone Desk hides the session list while keeping the existing timeline, notes and contact details.
    * Set Phone Desk as the default workspace for a role, with a Telephony Agent preset to get started.
    * Start a new call from the centered dialer and return to it when wrap-up finishes.
  </Expandable>

  <Expandable title="Improvements">
    * Availability controls sit beside the calling action.
    * Role setup uses clearer permission labels and a compact workspace selector.
  </Expandable>
</Update>

<Update label="September 22, 2026">
  ## Choose how your team answers calls

  <Frame>
    <img alt="Voice and telephony settings with a two-second automatic answer delay and 25 percent of available agents selected" />
  </Frame>

  Connect prepared agents automatically after a short ring, and ring a percentage of available teammates instead of interrupting everyone.

  <Expandable title="Features">
    * Turn on automatic answering and choose a delay from 1 to 20 seconds. Agents prepare their microphone once per dashboard load and keep that tab visible
    * Choose the percentage of available agents to ring. Open rounds up and prefers agents rung least recently
    * Enable telephony for your organization from Settings → Voice & Telephony with Voice settings write permission
  </Expandable>

  <Expandable title="Improvements">
    * Manual answering remains available, and existing organizations keep manual answering with all eligible agents rung until settings are changed
  </Expandable>
</Update>

<Update label="September 22, 2026">
  ## The command menu finds the thing, not just the page

  Press ⌘K (Ctrl+K on Windows) to search sessions, contacts, workflows, instructions, tags, phone agents, AI actions and past companion chats, switch organization, create any of them, act on the session or instruction you are looking at, use / commands to get there even faster, and hand anything you type to the companion with one key.

  <Expandable title="Features">
    * Type a page’s name or just its start, like agenti, and press Space to search that page (the highlighted row shows SPACE Search, and pointing at a row works too; Organization Settings searches your organizations). Sessions, contacts, workflows, instructions, tags, phone agents, AI actions and Companion chats all list the items themselves: type to narrow, press Enter to open that session, contact, workflow, instruction, phone agent or AI action, filter the inbox by that tag, or pick up that chat. Backspace or Esc steps back to the top level
    * Every list ends with Create: a session, contact, workflow, instruction, tag, phone agent, AI action or companion chat, right from the menu. When nothing matches, Create comes first
    * Phone agents show their voice, number and languages as flags; AI actions show their URL and HTTP method. Keyboard shortcuts sit under Actions, as Shortcuts
    * Sessions show as the same cards as the inbox. Find them by session number, several numbers at once, or title, or by session attributes: orderid:1231 plan:gold matches both, -plan:gold leaves those out, quotes keep spaces (name:"Jane Doe"), and attribute names complete as you type (Tab, Enter or : joins the name to the Sessions tag). Exact values come first, then close matches, so orderid:2044 also finds INV-2044. Your recent searches are one click away. Contacts are found by name, email or phone number
    * View sessions (⌘↩) opens the results in the inbox as a view
    * Actions for what is on screen: on a session, assign it (or take it), resolve or reopen it, change its status, move it to a team, edit its tags, start a sub-session, or open the contact’s history or profile; on an instruction, publish or unpublish it, open its settings (segments, channels, schedule) or test it; on the AI profile, publish or test it; on a workflow, activate or deactivate the version, view its runs, duplicate, copy its link or delete it; on a contact, start a session with them, copy their email or phone, block or delete them; on an AI action, test it or open its settings; on a phone agent, copy its number or ID or delete it; and each list’s own new button (new session, add contact, invite teammate, create tag). Assignment and team changes can be undone from the confirmation
    * Slash commands: type /session orderid:1231, /contact jane or /workflows refund (also /instructions, /tags, /phone-agents, /actions, /companion and /organizations, or /org) to jump straight to a match. A command turns into a tag as soon as you type a space after it. A lone / lists the commands, and Tab or Space completes the highlighted one
    * Press Tab to hand whatever you typed to the companion: it opens right where you are, in a new chat, already working on it. The same Ask Companion row appears under your results, and takes the place of a dead end when nothing matches
    * Results are grouped into sections, and Go to Instructions and Go to Organization Settings join the navigation list
  </Expandable>

  <Expandable title="Improvements">
    * Your organizations close the list, in their own group. While you search, every group, organizations included, sits where its best match lands, so the most relevant result is always first and Ask Companion is always last
    * Reopening the menu always starts fresh, whichever way it was closed
  </Expandable>
</Update>

<Update label="September 22, 2026">
  ## Team in the loop

  <Frame>
    <video />
  </Frame>

  When AI needs an answer from your team, it asks privately in Inbox and stays with the customer. Reply to the note and AI follows up with the answer in the same session.

  <Expandable title="Features">
    * Enable Team in the loop in Settings → Advanced for teams working in Inbox
    * AI mentions teammates based on your skills routing and notifies them when their help is needed
    * Answer in the note’s thread and AI follows up with the customer, quoting the question it is answering
    * Keep the AI needs help tag after the session ends, so you can filter and review past requests for team help
    * Replying directly to the customer keeps AI assigned; choose Take over from the AI assignee menu when you want to own the session
  </Expandable>
</Update>

<Update label="September 21, 2026">
  ## Connect an AI assistant with your sign-in, not an API key

  <Frame>
    <img alt="The approval screen for connecting an AI assistant, showing the organization being connected and what the connection is allowed to do" />
  </Frame>

  Paste one server URL into an AI assistant and sign in. You choose the organization to connect on the approval screen, and the connection acts as you — limited to what your role already allows.

  <Expandable title="Features">
    * Connect an AI assistant by pasting one server URL and signing in, with no API key to create, share, or rotate
    * Pick the organization on the approval screen, so belonging to more than one never connects the wrong one
    * Connections act as the person who approved them and can only do what that person’s role allows
    * Permissions resolve on every request, so a role change applies immediately without reconnecting
    * Review your connected apps and disconnect any of them from your settings
  </Expandable>

  <Expandable title="Improvements">
    * Work done through a connected assistant is recorded against the teammate who approved it, not as an anonymous key
  </Expandable>
</Update>

<Update label="September 20, 2026">
  ## Help Center: content rules retired

  Content rules and the checks that ran on save and on publish are gone from the Help Center. Publishing is a plain confirmation again, and translations follow the glossary and your translation prompt.

  <Expandable title="Improvements">
    * The Content Rules page, the Check content action and the pre-publish check are removed; nothing can block or delay a publish
    * Automatic translations are steered by the glossary and the translation prompt only
  </Expandable>
</Update>

<Update label="September 18, 2026">
  ## A faster way to write and organize your Help Center

  The Help Center editor now saves as you type, keeps one shared draft per article and language, and shows where every article stands at a glance. Arrange topics by dragging, nest them, and undo a delete.

  <Expandable title="Features">
    * Articles save as you type into a draft your whole team shares; nothing readers see changes until you publish
    * Every article shows its status in the language you are viewing: Live, Live with unpublished edits, Draft, Unpublished, Translating, or Not translated
    * The language menu shows the same status for every language, so you can see where a translation is missing before you switch
    * Drag topics and articles to reorder them, nest topics inside each other, and keep a separate order per language
    * Deleting an article or a topic can be undone, with its history, address and published state intact
    * Save a version without publishing, restore any older version into your draft, or discard the draft
  </Expandable>

  <Expandable title="Improvements">
    * Translations are produced when an article is published, from the version readers see, instead of on every save. Turn them off under Help Center settings, Languages
    * A translation you edited by hand is never overwritten by a later publish; use Re-translate from source when you want it to follow the source again
    * Open a language while it is still being translated and the text appears in place when it is ready
    * When two people edit the same draft, the second one is told and can reload or keep their changes
    * Large Help Centers stay quick: topics with hundreds of articles open and search instantly
  </Expandable>

  <Expandable title="Fixes">
    * Articles written in a language other than the primary one are now available to the AI as soon as they are published
  </Expandable>
</Update>

<Update label="September 15, 2026">
  ## Add teammates and phone numbers to a live call

  A teammate on a phone call can now bring more people onto it. Ring a colleague or dial an external number straight into the call, see who is on the line, silence anyone in your own headset, and remove anyone you added. Everyone hears each other, and the call keeps going when someone leaves.

  <Expandable title="Features">
    * Add a teammate or an external phone number to a live call from the call controls
    * See who is on the call and who is still being rung, mute any participant for yourself without affecting what others hear, and remove participants if you took the call
    * Invited teammates join with one click and can leave whenever they want without ending the call for anyone else
    * Call timelines in the inbox now show who joined, left, or was removed from a call
  </Expandable>

  <Expandable title="Improvements">
    * Hover over any control on the in-call card to see what it does
    * Recording and the live transcript keep covering the whole call as people join and leave
  </Expandable>
</Update>

<Update label="September 15, 2026">
  ## Each customer’s tools, connected in your widget

  <Frame>
    <video />
  </Frame>

  Let signed-in customers connect their own accounts, approve tool requests, and manage their connections in the widget. Choose the available services and tools from your dashboard.

  ### Personal accounts, managed from Actions

  Add a service once and let each signed-in customer connect their own account when a request needs it.

  * Choose personal accounts or one shared team account when adding a server
  * Keep personal connections scoped to the signed-in customer and account, across their sessions
  * Control which services and tools are enabled from the dashboard

  ### Approvals your customers control

  Connected services can ask for a form or a simple approval inside the widget. Customers can review the request before it continues.

  * Approve a simple request once, or remember approval for the same account, tool, inputs, and form
  * Open Connections from the widget session list to review saved approvals or disconnect a personal account
  * Remove one saved approval to ask again next time, while keeping the service connected

  ### Reuse a connection in your backend

  Opt in per service when your backend also needs access to a customer’s connected account.

  * Receive a connection-ready notification after successful authorization
  * Retrieve the current access token through a separately scoped server-side API key; credentials stay out of the widget
</Update>

<Update label="September 14, 2026">
  ## Workflow, handoff, and session reliability fixes

  A broad set of fixes makes sessions, workflows, integrations, reporting, and settings more dependable. Handoffs now preserve the right ownership, delayed AI replies respect newer activity, and common workflow and API failures recover cleanly.

  <Expandable title="Features">
    * Use the assigned team and support team from session data when routing or branching
    * Remove the AI from a session with the new Unassign AI action, leaving it available for your team
    * See each organization member’s assigned roles, and list or retrieve your organization’s role definitions
    * Export workflow notes alongside the rest of a session’s public event history
    * Resolving a session through the API now starts resolution workflows exactly once, including under concurrent requests
  </Expandable>

  <Expandable title="Improvements">
    * Session filters now accept up to 200 values and clearly reject unsupported fields instead of silently ignoring them
    * The Companion @ menu stays anchored to the composer, and deleting a team now clearly confirms the impact
    * Email spam handling can ignore unreliable mailbox labels for an organization while keeping reply-path detection consistent
  </Expandable>

  <Expandable title="Fixes">
    * Delayed AI assignments no longer reclaim a session or send an outdated reply after a teammate answers or a newer customer message arrives
    * Handoffs recover when an attempt cannot complete and no longer mark a session as handed off before its team assignment succeeds
    * WhatsApp replies triggered when a session is created now recognize the customer’s new message before checking the reply window
    * Editing a workflow no longer lets stale editor data overwrite its current trigger and block configuration
    * Directly received Zendesk messages now start contact-message workflows consistently
    * Email actions send to the requested recipient, and Instagram shares display clear story, reel, and post placeholders
    * Replies no longer expose JSON-escaped text, and long-running responses fail clearly instead of waiting indefinitely
    * Date-only report ranges now include the entire end date, and late sentiment updates refresh session data
    * Phone-agent actions with spaces or punctuation now run with valid names and validated operation references
    * Missing training records return a clear not-found response instead of an internal error
  </Expandable>
</Update>

<Update label="September 9, 2026">
  ## Pin your favorite reports and mini apps to the sidebar

  <Frame>
    <video />
  </Frame>

  Put the report pages and mini apps your team opens most right in the sidebar, in the order you want. Add them from the Reports & Apps section, drag to arrange, and everyone in the workspace sees the same list.

  <Expandable title="Features">
    * Pin any report page or a mini app built for the dashboard from the Add row; new pins land at the end of the list
    * Drag rows to set the order, and unpin from a row’s menu when it no longer earns its place
    * One shared arrangement for the whole workspace, edited by whoever manages helpdesk settings, the same permission as shared inbox views. It also lives in Settings › Workspace
    * Pinned mini apps open in the Companion browser filling the window, and share links now open the same way
    * Give a mini app its own icon so it stands out in the sidebar, from Edit name & icon; the Companion can set one when it creates an app
    * Report pages still need reports access, while a mini app follows its own sharing, so a teammate with a shared app sees the section even without report access
  </Expandable>
</Update>

<Update label="September 8, 2026">
  ## Saved inbox views, without the dashboard

  The views your agents pick from the inbox sidebar — "Phone — needs a human", "Assigned to me today" — can now be created, updated and shared from the API. Ask Companion for one, or build it alongside the workflow that fills it, instead of rebuilding it by hand.

  <Expandable title="Features">
    * New public-API endpoints to list, create, update and delete saved inbox views, gated by the new inbox-views:read / inbox-views:write scopes
    * New @opencx/mcp tools wrapping them: list\_inbox\_views, create\_inbox\_view, update\_inbox\_view, and delete\_inbox\_view
    * Views take the same filters as session search — channel, status, custom status, assignee, team, tags, sentiment, language, who the session is waiting on, date range — plus sorting and grouping
    * Two filters keep a saved view live: point it at whoever opens it, so one shared view means "assigned to me" for the whole team, and pick a rolling window (today, last 3 days, last 7 days) that never freezes to the day the view was saved
    * Share a view with everyone, with named teams, with named people, or with nobody but yourself — sharing follows the same permission as the dashboard, so someone who cannot share a view keeps it private
    * Views built in the dashboard with either/or and excluded conditions are listed and can be renamed, re-sorted and regrouped; their conditions change only when you deliberately send a new filter set
  </Expandable>
</Update>

<Update label="September 7, 2026">
  ## Companion, right where you need it — now in Widget v5

  <Frame>
    <video />
  </Frame>

  Bring Companion into your website with Widget v5, now in beta. Ask about the page in front of you, watch answers arrive, and configure the experience from the new Web chat and Advanced settings pages.

  ### Companion, inside your website

  A small launcher opens into a floating workspace that stays beside the page your customer is using.

  * Switch between floating, sidebar and fullscreen layouts as the task grows
  * Mark a region, draw a box, circle or arrow, add a note, and attach the marked screenshot to your message
  * Share the current page and mention records from your app so the agent knows what you mean
  * With streaming enabled for your organization, see answers as they arrive and stop a reply when you need to change direction
  * Keep the classic popover if you prefer; Companion is a separate display option

  ### A new home for Web chat settings

  <Frame>
    <img alt="Web chat settings with a masked widget token, website feature controls, and a live Widget v5 preview" />
  </Frame>

  The Web chat channel page brings your widget token, website features and a live preview together.

  * Copy your widget token and open the installation guide from the same page
  * Control voice dictation, rich replies, page context, page highlights and clarifying questions where you configure your web channel
  * Preview the widget beside your settings; saved feature changes refresh the preview

  ### Advanced features, across your channels

  The Advanced settings page brings agent-wide capabilities together, with clear controls for features included in your organization and those available on request.

  * Configure progress updates and whether the agent remembers past sessions
  * Enable available scheduled follow-ups, task plans, a workspace and mini apps, or request access from the feature row
  * Scheduled follow-ups let the agent check back and continue the same session later
  * Feature switches save as you change them; handoff behavior remains in Handoff settings

  ### Get started with a coding skill

  Install our widget skills to help your coding assistant configure a new integration or migrate an existing site to v5.

  * Choose the integration skill for setup and Companion configuration, or the migration skill for v4-to-v5 checks
  * The setup guide includes the npx installation commands and keeps the v5 beta version choice explicit
</Update>

<Update label="September 1, 2026">
  ## Calling, rebuilt around the agent on the line

  A big round of upgrades for teams taking phone calls in the inbox: hold that truly holds, dialing that tells the truth about what happened, breathing room between calls, and new controls for sounds, tabs, and pop-out calling.

  <Expandable title="Features">
    * Putting a call on hold now really parks the caller: they hear hold music, neither side hears the other, and resuming restores your mic and speaker exactly as they were
    * The caller’s number is shown while the phone rings, with one-click copy; an organization setting decides whether it is visible while ringing or only after the call is accepted
    * Call sounds are yours to configure: pick a ringtone, set its volume, and turn on an end-of-call cue, with a notification when the dashboard tab is in the background
    * Wrap-up time between calls: a breather before the next call can ring you, with a countdown, "I’m ready" to end it early, one click to add more time, and your wrap-up status visible to teammates
    * Open sessions in tabs: a new preference keeps several sessions open side by side
    * Pop a live call out into its own compact window and keep working anywhere else in the dashboard; the audio never moves, and you can hang up from either window
  </Expandable>

  <Expandable title="Improvements">
    * Outbound dialing is honest end to end: you hear ringback while the phone rings, and the timer and "Connected" state begin only when the customer actually picks up
    * Agents already on a live call are never rung for another one
  </Expandable>

  <Expandable title="Fixes">
    * Outbound call outcomes are labeled truthfully: Declined, Busy, Cancelled, and Couldn’t connect, instead of every unanswered dial reading as failed
    * Hanging up while the phone is still ringing records the call as cancelled rather than "no answer"
    * The end-of-call sound plays once per call, even when a callback lands in the same session
    * A call that fails at the same instant from two directions no longer leaves the agent parked in a stuck ringing screen
    * Pressing "need more time" twice in quick succession now extends your wrap-up twice
  </Expandable>
</Update>

<Update label="August 30, 2026">
  ## Live transcripts for calls answered by your team

  Calls handled by human agents now produce a live, speaker-labeled transcript in the session while the call is still happening. Available per organization on request.

  <Expandable title="Features">
    * Every word of a call answered by a team member appears in the session within moments, labeled with who said it: the customer, or the agent by name
    * Works everywhere your team talks to customers by phone: inbound calls answered directly, calls handed off from the AI agent, and outbound calls your team places
    * Transcripts keep up when callers switch languages mid-call
    * Sensitive details in call transcripts are redacted the same way they are in chat messages
    * Call summaries now build on the live transcript, so they are ready right after hang-up and cover the entire call, however long it ran
  </Expandable>
</Update>

<Update label="August 30, 2026">
  ## Hand the companion a file

  <Frame>
    <img alt="The companion composer with contacts.csv attached, asking to add the contacts to the renewal campaign" />
  </Frame>

  You can now attach files to a companion message. Drop in a spreadsheet of contacts, a screenshot, or a document, and the companion reads it as part of your request.

  <Expandable title="Features">
    * Attach a file from the paperclip, drag it onto the composer, or paste it straight from your clipboard
    * Spreadsheets and CSVs are read row by row, so "add these contacts to the campaign" works on the file itself, not on text you pasted in
    * Images, PDFs, and text files work too — share a screenshot of an error and ask what went wrong
    * Up to 10 files per message, 25 MB each; if you drop in more, the composer says so instead of quietly leaving some out
    * What you attached stays visible under your message when you come back to the session
  </Expandable>
</Update>

<Update label="August 30, 2026">
  ## Email, exactly as it was sent

  <Frame>
    <img alt="An email session as a threaded conversation, with the original inbound email rendered in its own branded layout" />
  </Frame>

  The inbox now treats email like email. Sessions read as a threaded conversation, and any inbound message can be opened in its original form — the sender's own layout, colors, and images — right next to the transcript.

  <Expandable title="Features">
    * Email sessions render as a familiar thread: earlier messages collapse into compact cards, and each email shows its sender, recipients, and subject
    * Open the original of any inbound email to see it exactly as the sender wrote it — fonts, colors, tables, signatures, and inline images included — rendered safely in a fully isolated frame
    * Remote images stay off until you choose to show them, so opening an original never signals anything back to the sender
    * When a customer answers inside the quoted part of their reply, that content now stays on the session and a one-line notice marks the change — nothing they wrote is lost
    * Replies you send appear on the thread with a delivered state, so you can tell at a glance what actually went out
  </Expandable>
</Update>

<Update label="August 27, 2026">
  ## Simpler rules for editing and deleting shared inbox views

  Every shared view used to carry its own private list of people allowed to edit it, which meant even an admin got "you do not have permission" on a view someone else made. That list is gone. One rule now decides everything: the person who created a view can always change it, and so can anyone holding the "Shared inbox views" permission — admins included.

  <Expandable title="Improvements">
    * Admins, and anyone with the "Shared inbox views" permission, can rename a shared view, change its filters, or delete it — including views made by teammates who have since left
    * Those same people now see every shared view in their list, not only the ones shared with them, so there is nothing to track down before tidying up
    * Sharing a view now decides one thing: who can see it. The "Who can edit" picker is gone, because the permission answers that question instead
    * Views you keep to yourself are untouched. They stay invisible to everyone else, admins included, and only you can edit or delete them
    * If you previously gave a teammate edit rights on one specific view, they still see that view but can no longer change it unless their role includes the "Shared inbox views" permission
  </Expandable>
</Update>

<Update label="August 25, 2026">
  ## Screenshots inside macros, right where each step needs them

  <Frame>
    <img alt="An agent reply in the inbox: step 1, its screenshot, step 2, its screenshot" />
  </Frame>

  Macros can now carry images between their steps. Put a screenshot under "Step 1", another under "Step 2", and the customer receives the walkthrough in that order — no more re-attaching files by hand on every reply.

  <Expandable title="Features">
    * Paste, drop, or type /image in the macro editor to place an image exactly where it belongs in the text; the image stays with the macro, so there is nothing to re-upload when you send
    * Inserting the macro in the composer shows the images in place, and they go out inline on the web widget and over email
    * On WhatsApp and Instagram the images are delivered as separate attachments before the text; the macro editor tells you when a macro will behave this way
    * The inbox timeline shows the images in the sent reply, and the macro list and macro picker show how many images a macro carries
  </Expandable>
</Update>

<Update label="August 25, 2026">
  ## Phone calls that never leave a caller hanging

  A round of voice upgrades focused on dependability. The phone agent handles quiet moments gracefully, always says goodbye before ending a call, and runs isolated from the rest of the platform so nothing else can interrupt a live call.

  <Expandable title="Improvements">
    * Live calls are now fully isolated from the rest of the platform, so a busy dashboard or heavy background work can never affect a call in progress
    * The "are you still there?" check-in now sounds natural and picks up from the conversation instead of repeating a canned line
    * The phone\_call.ended event now fires after your Call Finished workflows complete and carries their custom data, so downstream automations always see the full picture
  </Expandable>

  <Expandable title="Fixes">
    * The phone agent no longer hangs up on a caller who answers its still-there check-in
    * A quiet caller is never dropped silently: the agent always speaks a goodbye before ending an idle call
  </Expandable>
</Update>

<Update label="August 25, 2026">
  ## Security emails: admins know the moment something sensitive changes

  Every admin now gets an email when something security-sensitive happens in the organization. Each alert matches an entry in the audit log, says exactly who did what, when, and from where, and the critical ones cannot be turned off.

  <Expandable title="Features">
    * A member joining or leaving, an Admin role being granted, role permissions changing, a new API key, or PII redaction being turned on or off emails every admin, always
    * Connecting an MCP server, creating a secret, or changing your webhook endpoint notifies admins too, and each of these can be turned off per type in Settings, under Notifications
    * Every email names who performed the change, what changed, when, and from where, with a one-click link to review or undo it
    * Alerts are matched one-to-one with audit log entries, so the email trail and the audit trail never disagree
    * Delivery is dependable: temporary hiccups are retried, routine bulk imports never flood inboxes, and only admins ever receive these emails
    * Reply to any security email and it reaches our security team directly
  </Expandable>
</Update>

<Update label="August 18, 2026">
  ## Sub-folders, pins and custom order for AI instructions

  <Frame>
    <img alt="A quick tour of the AI Instructions sidebar: nested folders, dragging instructions into folders, the folder menu with sub-folders and pinning, and a pinned folder at the top" />
  </Frame>

  The AI Instructions folder list is now yours to arrange. Nest folders inside folders, pin the ones you open every day to the top, and drag the rest into the order you want, or flip to A to Z. Pins and ordering are personal, so every teammate keeps their own view.

  <Expandable title="Features">
    * Sub-folders: create folders inside folders as deep as you like, drag folders and instructions into any folder, and see the full instruction count for a folder including everything nested under it
    * Pin to top: pin the folders you use every day so they always sit above the rest, per user
    * Drag and drop: drop a folder or instruction onto a folder to move it inside, or between rows to place it exactly there, at any level, with the mouse or the keyboard
    * Custom order: the order you drag folders and instructions into is saved to your account, at every level; instructions and sub-folders mix freely, so an instruction can sit above a sub-folder
    * New folders are created in place: choose New folder or New sub-folder, type the name, press Enter
    * A to Z: switch the folder list to alphabetical from the sort menu and back to your custom order at any time
    * Folder-wide actions follow the tree: visibility, export and delete on a folder include its sub-folders, and a phone agent given a folder as a knowledge source also gets the sub-folders inside it
    * Moving an instruction shows the nested folder tree, and the folder search in that dialog now works
  </Expandable>
</Update>

<Update label="August 14, 2026">
  ## Talk instead of type — voice dictation everywhere

  Speak your replies instead of typing them. Every Companion composer now has a microphone, and a keyboard shortcut turns any text field in OpenCX into a dictation surface — your words appear live as you talk, punctuated and capitalized for you.

  <Expandable title="Features">
    * Click the microphone in any Companion composer and just talk — words stream in live as you speak
    * Dictate into any text field: focus it and press Option+M on Mac or Alt+M on Windows — replies, internal notes, CC lines, settings, anywhere you can type
    * Speak your formatting: say "new line", "new paragraph", or "bullet point" — bullet points become real lists when you stop
    * Say "scratch that" to remove your last sentence, and in Companion say "send message" to send completely hands-free
    * Dictate in any language — transcription follows the language you speak, and the spoken commands also work in Spanish, French, German, Portuguese and Italian
    * Press Escape to stop at any time — the microphone is never left open, and audio never touches OpenCX servers
    * Built for accessibility: full keyboard operation, screen-reader announcements, and reduced-motion support
  </Expandable>
</Update>

<Update label="August 13, 2026">
  ## Read every session in your language

  <Frame>
    <img alt="The Translation menu in a session — a searchable target-language picker, ignore languages, display style, and translated content options" />
  </Frame>

  The inbox now translates sessions into your language as you read them. Pick a target language once from the session menu and every session in another language — messages, previews, summaries — shows up in a language you read.

  <Expandable title="Features">
    * Pick a target language from the session menu — messages in other languages are translated as you read them
    * Ignore languages you already read — sessions in those languages stay untranslated
    * Choose a display style: show the translation beneath the original, or only the translation
    * Choose what gets translated — customer messages, agent and AI replies, workflow and sequence messages, and internal notes each have their own toggle
    * Session previews and summaries in the session list translate too, along with voice call summaries — the whole inbox reads in your language
    * Affects your view only — replies you send reach customers exactly as you wrote them
  </Expandable>
</Update>

<Update label="August 9, 2026">
  ## Connect any MCP server to your AI agent

  <Frame>
    <img alt="The actions directory — your APIs, connected MCP servers, and a gallery of popular servers to add in one click" />
  </Frame>

  Your agent can call tools from any MCP server — Linear, Notion, Stripe, Slack, or one you host yourself. Add it from the actions directory, approve it with OAuth (or paste a token when that is what the server wants), and choose exactly which of its tools the agent may use.

  <Expandable title="Features">
    * The actions page is one directory: your APIs, your MCP servers, and a gallery of popular servers — Slack, Linear, Notion, Stripe, HubSpot, Intercom
    * One-click connect: OpenCX detects how a server authenticates and walks the right path — an OAuth consent screen, a token prompt, or nothing at all
    * Per-tool control: switch individual tools off; tools a server publishes later stay available by default
    * Each server has its own page listing exactly what the agent can call, grouped by whether tools read or write
    * Tools reach the agent namespaced by server (slack\_\_send\_message), so they can never collide with your actions
  </Expandable>
</Update>

<Update label="August 9, 2026">
  ## Named secrets for action credentials

  <Frame>
    <img alt="The Secrets card in settings — write-only encrypted credentials edited inline, next to Global Headers" />
  </Frame>

  Define a credential once in Settings, then reference it from any action header by name. The value is write-only — encrypted, never displayed again anywhere, and decrypted only at the moment a request actually fires. Unlike a global header, a secret travels only on the requests that reference it, so one workspace can talk to many systems without every call carrying every key.

  ### Reference it from any action

  <Frame>
    <img alt="The secret picker in an action header editor — typing two braces offers the org’s secrets" />
  </Frame>

  Type `{{` in any action header value to pick a secret, or write `{{secrets.<name>}}` directly. The secret travels only on the requests that reference it — and a header whose secret is missing is dropped, never sent with the raw placeholder.

  * Write-only by design: no screen, API, or export ever returns the value after creation
  * Each secret shows how many actions reference it before you delete it
  * MCP server auth headers accept the same references
</Update>

<Update label="August 4, 2026">
  ## Block abusive IPs on your own rules, not by hand

  Blocking an IP used to mean noticing the abuse, digging the address out of somewhere, and banning it forever. Now a workflow can count how many sessions an address has opened in the last few minutes and block it on whatever threshold you consider abusive — and blocks can expire on their own, so a shared office or mobile-carrier address is never banned permanently by mistake. Every session in the inbox shows the address it came from, and session exports can carry it too.

  <Expandable title="Features">
    * Three new workflow actions — Block IP, Unblock IP, and Count Recent Sessions From IP — so a rule can decide for itself when to block
    * Workflows can read the visitor address as `{{ticket.clientIp}}`
    * Blocks can expire — set a number of hours and the block lifts itself
    * Every session in the inbox now shows the IP it came from, with a block button beside it
    * Session exports can include the visitor IP, plus how many sessions and distinct contacts came from that address within the export — one address with many contacts is someone minting a throwaway identity per message
    * Public API and MCP gained expires\_in\_hours on blocking, plus a session-activity endpoint and a list\_session\_ips tool for building your own rules
  </Expandable>

  <Expandable title="Improvements">
    * The visitor address is now recorded when a session is created, not only when the first message arrives — so a burst of sessions that never get a message is still counted
    * Blocked IPs now shows when each block expires, and marks lapsed ones
    * Re-blocking an address whose block has already lapsed re-arms it instead of quietly doing nothing
    * Blocklist screens and API docs now say plainly that IP blocking applies to the web widget — email and WhatsApp arrive through the provider’s servers and carry no visitor IP, so block those by domain or contact
  </Expandable>
</Update>

<Update label="August 2, 2026">
  ## Design your own CSAT surveys

  <Frame>
    <img alt="The CSAT web feedback page editor holding a custom HTML template, with starter template and preview controls" />
  </Frame>

  Your CSAT surfaces are now fully yours: bring your own HTML for the feedback page customers land on and for the CSAT request email, edit and preview both from Settings → CSAT, and manage them via the public API or by just asking Companion.

  <Expandable title="Features">
    * Custom CSAT feedback page — provide full HTML; simple data-csat-\* attributes wire up score buttons, comments, and thank-you views, with a JS API for custom flows
    * Custom CSAT request email and subject line, sent exactly as you wrote them, with per-score rating link variables
    * Template editors with live previews (click a score in the email preview to walk the whole email → page flow), starter templates, and test sends
    * Companion can read and edit your CSAT templates — ask it to design a survey matching your brand
    * Public API endpoints and MCP tools for CSAT settings (csat:read / csat:write)
    * New X (Twitter) channel — connect your own X developer app and support customers over DMs
    * Hide noisy session and contact attributes from inbox panels with wildcard patterns
    * Copy a full session transcript from the inbox in one click
    * Pick a default sending inbox so the composer "From" stays put
    * New email template slots:  and opt-in , now copyable chips
    * Jump straight to the linked Zendesk ticket from the session side panel
    * Twilio Flex: save settings without re-provisioning and sync chosen task attributes onto the contact
    * New option to disable the inbox notification sound
  </Expandable>

  <Expandable title="Improvements">
    * Faster, smoother dashboard first load — themed splash, lighter startup, automatic recovery after deploys
    * Email intake hardening: Gmail-misfiled spam is pulled in and expired mailbox connections recover automatically
    * "Assumed resolved" sessions now display as Resolved everywhere
  </Expandable>

  <Expandable title="Fixes">
    * Re-rating a CSAT survey keeps score history visible, attaches follow-up feedback to the latest score, and never wipes a saved comment
    * Zendesk no longer creates duplicate tickets when the AI resolves a session, and closes survive conditional required-field cascades
    * Workflow internal notes post to Salesforce as unpublished comments, invisible to customers
    * Email threading: the invisible reference token is hidden, replies no longer fork new sessions, and Outlook Web quotes strip cleanly
    * AI suggestions are never quoted back at the customer in email replies
    * Fixed an inbox freeze caused by empty attribute filter values
    * Reply attachments from workflows are persisted on the session timeline
    * Voice agents stop interrupting callers who dictate numbers slowly
  </Expandable>
</Update>

<Update label="August 2, 2026">
  ## Block abusive visitors by IP

  Settings → Autopilot now has a Blocked IPs list alongside blocked contacts and domains. Block a single address or a whole CIDR range and that visitor can no longer reach your AI assistant — useful when someone keeps creating throwaway contacts, so contact- and domain-blocking never bite.

  <Expandable title="Features">
    * Block a single IP (203.0.113.7) or a CIDR range (203.0.113.0/24), IPv4 and IPv6
    * Once a session is seen from a blocked address the block applies on every channel
    * Write your own message for blocked visitors, or keep the default
    * Manage the list from the API and MCP tools alongside blocked contacts and domains
  </Expandable>

  <Expandable title="Improvements">
    * The real visitor IP is now read from Cloudflare’s CF-Connecting-IP header, which cannot be forged by the client
  </Expandable>

  <Expandable title="Fixes">
    * Blocked visitors no longer get an "Internal Server Error" in the widget — they now see a short message explaining they cannot contact the company right now
  </Expandable>
</Update>

<Update label="July 27, 2026">
  ## Enterprise SSO with SAML and OIDC

  Sign in through your own identity provider — Okta, Entra, OneLogin, and friends — with DNS-verified domains and just-in-time provisioning that grants new users a least-privilege role.

  <Expandable title="Features">
    * Enterprise SSO via SAML or OIDC with just-in-time provisioning, managed from Settings → Security
    * Every phone call is now its own record with a dedicated bubble in the session timeline
    * CSAT for Zendesk conversations — surveys delivered as a Sunshine link
    * Infobip: AI-queue conversations are claimed automatically when the chatbot releases them
    * Tag and category search on the public API and MCP list tools
  </Expandable>

  <Expandable title="Improvements">
    * Workflow editor: one-click auto-layout, hovered-node path highlighting, and cleaner else-branch layout
    * OpenCX skips its own CSAT when Zendesk already offered a survey on the ticket
    * Companion writes better agent profiles and grounds onboarding test sessions in your knowledge base
    * The voice picker now lists only proven voices
  </Expandable>

  <Expandable title="Fixes">
    * Fixed an inbox crash for users browsing with Google Translate enabled
    * Pasting an item title into AI-instructions search now finds it, and pasted text stays readable in dark mode
    * Ticket-resolved workflows fire even when closing the external ticket fails
    * Public blocklist endpoints attribute blocks to the API token actor instead of failing
  </Expandable>
</Update>

<Update label="July 22, 2026">
  ## Crawl password-protected websites

  The website crawler can now sign in to your protected sites. Add HTTP Basic, bearer token, cookie, or custom-header credentials to a website datasource and every crawl authenticates automatically — credentials are encrypted at rest and never shown again after saving.

  <Expandable title="Features">
    * Crawl sites behind HTTP Basic, bearer tokens, cookies, or custom headers
    * Credentials are encrypted at rest and never returned by the API or dashboard
    * Set, replace, or clear site authentication via the Crawl API and MCP tools
  </Expandable>
</Update>

<Update label="July 22, 2026">
  ## See how your team adopts Companion

  <Frame>
    <img alt="The Companion Adoption report — active teammates, sessions, and what teammates use Companion for" />
  </Frame>

  A new Companion Adoption report shows how your team uses the AI copilot — active teammates against seats, sessions and turns, what they use it for, and escalations to the OpenCX team.

  <Expandable title="Features">
    * New Companion Adoption report under Reports
    * Active teammates vs. seats, sessions, and average turns per session
    * A breakdown of what teammates actually use Companion for
    * Escalations to the OpenCX team, tracked over time
  </Expandable>
</Update>

<Update label="July 14, 2026">
  ## Analytics, rebuilt for speed

  <Frame>
    <img alt="The Impact Dashboard on a high-volume workspace, showing the AI-solved total, the automation percentage and the flow chart" />
  </Frame>

  The Impact Dashboard is now much faster. It loads in moments, even with millions of conversations, and Companion’s analytics and the dashboards you build with it got the same speed boost.

  <Expandable title="Improvements">
    * The Impact Dashboard loads in moments, even on the busiest workspaces
    * Companion answers your analytics questions faster
    * Dashboards you build with Companion stay fast as your data grows
  </Expandable>
</Update>

<Update label="July 6, 2026">
  ## Introducing Companion Apps

  <Frame>
    <video />
  </Frame>

  Now you can build your own tools right inside the platform. Describe the dashboard or inbox widget you want, and Companion turns it into a working app in minutes, shaped around how your team works.

  ### Custom reports for the metrics that matter

  <Frame>
    <img alt="A custom reports dashboard built with Companion" />
  </Frame>

  Track resolution, CSAT, SLAs, and cost the way your team measures them. Describe the custom report or dashboard you want, and Companion builds it on your live data — the answers you need, ready in minutes.

  * See where conversations resolve, stall, or escalate
  * Go from a question to an answer in minutes

  ### Faster resolutions, without the tab-switching

  <Frame>
    <img alt="A delivery map widget pinned beside a conversation in the inbox" />
  </Frame>

  Bring the exact context a conversation needs into the inbox — order status, a live delivery map, account history — so agents answer on the spot instead of digging through other tools.

  * Cut handle time with the context already in reach
  * Surface live order, delivery, and account details
</Update>

<Update label="July 1, 2026">
  ## Ask Companion any analytics question

  <Frame>
    <img alt="Companion answering a custom analytics question" />
  </Frame>

  When the built-in reports don’t cover it, Companion now runs the analysis for you — custom breakdowns, percentiles, trends, and cross-cuts over your conversations, CSAT, SLA, agents, and tags. Just ask in plain language.

  <Expandable title="Features">
    * Ask Companion the questions the standard reports don’t answer — “median handle time by channel last month”, “CSAT vs queue-wait by channel”, “SLA breach rate by team” — and it computes the answer over your live data
    * Covers custom breakdowns, percentiles, correlations, and time-bucketed trends across sessions, messages, CSAT, SLA, agents, contacts, and tags
  </Expandable>
</Update>

<Update label="June 29, 2026">
  ## Companion can now run your actions

  Ask Companion to run one of your actions and it makes the real request for you — with your confirmation — then shows you the response. It can run your workflows too.

  <Expandable title="Features">
    * Companion can run a configured action on your behalf — it makes the action’s real HTTP request and returns the response, always asking you to confirm first
    * Companion can run your workflows the same way
    * Run an action or workflow with a conversation’s in-session context — its org variables, contact identity, and headers — so it behaves exactly as it would for the AI agent
  </Expandable>
</Update>

<Update label="June 28, 2026">
  ## See which Instructions, Knowledge, and Actions your AI uses

  Every AI reply now records the Instructions, Knowledge Base articles, and Actions it drew on. Each one gets a usage view — how often it was available to the AI versus actually used, the handoffs tied to it, and the conversations that used it — and you can filter your inbox by them.

  <Expandable title="Features">
    * Every AI Instruction, Knowledge Base article, and Action now has a usage view — Available (the AI had it in context), Used (it actually applied or cited it), and the related Handoffs
    * Open the list of conversations that used a given Instruction, Action, or KB article and jump straight into any of them in the inbox
    * Filter a resource's usage by date range
    * Filter conversations by the Instructions, Actions, or Knowledge Base articles the AI used in them
  </Expandable>
</Update>

<Update label="June 5, 2026">
  ## Freshdesk ticketing, HubSpot AI fields, and richer session exports

  Connect Freshdesk as a ticketing system, let AI fill your configured HubSpot fields, and export sessions with your own custom data columns — with live progress while the export runs.

  <Expandable title="Features">
    * Freshdesk ticketing integration — connect Freshdesk and hand conversations off as tickets
    * HubSpot AI fields — the AI fills in your chosen HubSpot ticket and contact fields when it hands off or resolves a conversation, and the values show in your inbox
    * In HubSpot assist mode, conversations about topics you choose can go straight to the AI for a public reply
    * Add your own custom data columns to session exports — for both conversations and contacts
    * Your existing custom data keys are suggested as you type when setting up export columns
    * Session exports include handoff reason and explanation columns
    * Get notified when a session export finishes — the notification takes you straight to it
    * Session export filters now match the inbox, with a preview of the file before you export
    * Archive policies — archived insights keep tracking new conversations and alert you when an issue comes back
    * Approve or reject suggested insight categories in bulk
    * AI summaries for phone calls
    * Infobip conversations are labeled when the AI hands off or resolves, so your team can spot AI activity at a glance
    * Actions can now be enabled for the API channel
    * Create a session and its contact in one API call, including custom data on both
    * Session custom data is now available on the public session API
  </Expandable>

  <Expandable title="Improvements">
    * Session exports show live progress with a count and estimated time remaining
    * Large session exports are faster and more reliable
    * Email replies thread into the right conversation more reliably
    * Conversation tags are applied more carefully, following each tag's description
    * Voice agents handle interruptions more naturally
    * Better dark mode for phone agents
  </Expandable>

  <Expandable title="Fixes">
    * Fixed cases where the AI replied twice to the same customer message or reopened a resolved conversation
    * Pre-handoff workflows run once per handoff, even when messages arrive in quick succession
    * Conversations are only assigned to you when you actually start writing a reply
    * Conversations with no messages yet now show up in inbox filters, counts, and exports
    * Macros keep their line breaks when you reopen them for editing
    * Incoming email replies no longer include quoted history from earlier messages
    * Closing a conversation in the dashboard now closes the linked Zendesk ticket
    * Conversations whose Zendesk ticket was already closed no longer run into errors
    * The AI now reads the email subject on Zendesk email tickets
    * Conversations closed by a workflow are no longer counted as resolved by the AI
    * Fixed duplicate AI replies in Twilio Flex conversations — messages are now processed directly, so customers get a single timely response
    * Rapid messages on WhatsApp, Instagram, and Messenger no longer create duplicate contacts or conversations
    * Images and files sent over Infobip now arrive in the inbox, and the handoff message reaches the customer before the conversation moves to a human agent
    * Tag names with unsupported characters are rejected when created, so a bad tag can no longer stop the AI from replying
    * Publishing AI instructions works reliably again
    * Reports load reliably and match the dashboard theme
    * Editing AI instructions and the AI profile now requires the right permission — others get a read-only view
    * Voice agents pronounce spelled-out letters correctly in Spanish, support Arabic dialect voices, and no longer prompt for input mid-transfer
  </Expandable>
</Update>

<Update label="June 4, 2026">
  ## Excluding a page now removes it from your AI

  When you exclude a crawled page — or add an exclude rule to a website source — its content is removed from your knowledge base, so your AI stops answering from pages you meant to hide.

  <Expandable title="Fixes">
    * Excluding a crawled page deletes its content from your AI instead of leaving it citable
    * Adding an exclude path now cleans up already-crawled pages that match it
    * Re-including a page requeues it for the next crawl to rebuild its content
  </Expandable>
</Update>

<Update label="May 29, 2026">
  ## Keep insight categories organized — and catch issues when they come back

  Up to 150 insight categories with a usage meter. Companion helps merge duplicates. Resolved issues reopen when they happen again, and you can see similar insights at a glance.

  <Expandable title="Features">
    * Up to 150 categories with a usage bar and a warning when you are at the limit
    * Create, edit, approve, or merge categories from Companion
    * Companion can guide you through cleaning up duplicate categories at scale
    * Similar insights at the bottom of each insight shows related themes
    * Resolved insights reopen automatically when the same issue happens again
  </Expandable>

  <Expandable title="Improvements">
    * Category settings stay fast with long lists
    * Sensible limits on category name and description length
    * Insight analysis stays reliable with many categories
    * Usage meter shows a loading state while counts update
  </Expandable>
</Update>

<Update label="May 29, 2026">
  ## Talk about insights with your team

  Comment on insights like the inbox — threads, @mentions, notifications, and jump to the right comment from a notification.

  <Expandable title="Features">
    * Comment threads on insights with @mentions and reply notifications
    * Notifications take you to the exact comment with a brief highlight
  </Expandable>

  <Expandable title="Fixes">
    * Comments show up right away when you open a discussion
    * @mention menu works on all training content
    * Reply notifications show the right title on desktop
  </Expandable>
</Update>

<Update label="May 29, 2026">
  ## Schedule when AI instructions apply

  Set start and end dates for AI instructions. Before you publish, see what is scheduled, live, or already past.

  <Expandable title="Features">
    * Pick date and time windows when each instruction is active
    * Scheduled instructions apply to voice and when copying settings to another workspace
    * Draft view groups instructions as scheduled, active, or expired
  </Expandable>

  <Expandable title="Fixes">
    * Date picker does not fill in an end date until you are ready
    * Publishing schedule-only changes does not create stray drafts
  </Expandable>
</Update>

<Update label="May 25, 2026">
  ## Smarter email and Twilio Flex in the inbox

  Control how each email channel handles mail, use reusable templates, and see Twilio Flex agent messages in the inbox.

  <Expandable title="Features">
    * Choose how each email channel handles incoming mail
    * Email replies land on the right conversation more reliably
    * Reusable email templates you can manage and use with Companion
    * Twilio Flex agent messages show in the inbox like other agent replies
  </Expandable>

  <Expandable title="Improvements">
    * Voice agents recognize your product names and jargon more accurately
    * See why a conversation was assigned to a particular agent or team
  </Expandable>
</Update>

<Update label="May 25, 2026">
  ## Start WhatsApp chats from the dashboard, plus new workflow steps

  Open a new WhatsApp conversation from the dashboard. Workflows can run in order, assign smarter, and pull data from pages, documents, and spreadsheets.

  <Expandable title="Features">
    * Start a new WhatsApp conversation from the dashboard
    * Run workflow steps in order when a ticket is created
    * Auto-assign can pick the right team, then assign an agent
    * New steps: fetch a webpage, parse a document, read spreadsheets
    * HubSpot workflows can create more than one ticket per conversation when enabled
  </Expandable>

  <Expandable title="Improvements">
    * Workflow run history loads faster for workflows with many branches
  </Expandable>

  <Expandable title="Fixes">
    * Intercom: fewer duplicate or out-of-order replies after handoff
    * Front: conversations stay unassigned after AI replies when they should
    * WhatsApp: contacts with the same phone number no longer duplicate
    * Inbox filters work with numeric custom fields
  </Expandable>
</Update>

<Update label="May 18, 2026">
  ## Clearer roles and billing in settings

  Roles and permissions are easier to manage. Billing connects to Stripe for simpler subscription handling (for admins).

  <Expandable title="Features">
    * Redesigned roles and permissions — easier to see who can do what
    * Billing tied to Stripe with straightforward subscription management for admins
  </Expandable>

  <Expandable title="Improvements">
    * Team page shows role names instead of long permission lists
    * Billing overview focuses on paying customers by default
  </Expandable>

  <Expandable title="Fixes">
    * Admins see canceled, paused, and overdue subscriptions when linking billing
    * Billing page no longer shows Free plan when a paid subscription exists
  </Expandable>
</Update>

<Update label="May 18, 2026">
  ## Infobip, WhatsApp surveys, and a better inbox

  Infobip as a channel, WhatsApp satisfaction surveys with tap-to-rate lists, filter by external ticket ID, resize the reply box, and send files without a message.

  <Expandable title="Features">
    * Infobip Conversations as a support channel
    * Customer satisfaction surveys on WhatsApp with tap-to-rate lists
    * Filter conversations by external ticket ID
    * Resize the reply box; add internal notes anywhere; send attachments without text
    * HubSpot can create tickets without contact email or phone when you allow it
    * Images in Freshchat show inline for agents and customers
  </Expandable>

  <Expandable title="Improvements">
    * Zendesk auto-fill works with more field types
    * Zendesk custom fields update more reliably
    * Auto-tagging considers attachments
    * Choose what happens when the AI detects a prohibited topic — per channel
    * Azerbaijani and Bengali added as supported languages
    * Workflow editor autocomplete works reliably again
  </Expandable>

  <Expandable title="Fixes">
    * Zendesk conversations no longer look AI-assigned when the AI will not reply
    * Long URLs and emails truncate cleanly in the conversation list
  </Expandable>
</Update>

<Update label="May 11, 2026">
  ## Companion answers faster and shows more as it works

  Companion starts quicker, shows rich updates while it works, and lets you keep typing. Look up help on docs.open.cx when you are stuck.

  <Expandable title="Features">
    * First message in Companion lands faster
    * See structured updates in the chat as Companion works
    * Keep typing while Companion is running; progress shows between steps
    * Ask Companion to look up answers on docs.open.cx
  </Expandable>

  <Expandable title="Fixes">
    * Switching chats no longer shows duplicate Companion messages
    * Very long opening messages no longer fail to send
    * Companion shows its reasoning again, including AI Identity help
  </Expandable>
</Update>

<Update label="May 11, 2026">
  ## Freshchat routing, shared settings, and macros that run workflows

  Shared workspace settings, smarter Freshchat handoffs and tags, macros that start workflows, and more control over assignments.

  <Expandable title="Features">
    * One set of workspace settings for the whole team
    * Freshchat handoffs can route to a specific group
    * Freshchat tags stay in sync with channel and group names
    * Workflows can start when an agent sends a macro
    * Unassign open conversations; react when agents go available or away
    * Pick which Front signature AI replies use
    * Set how many AI chats Twilio Flex can handle at once
    * Agent-reply webhooks include assignee and custom contact fields
  </Expandable>

  <Expandable title="Improvements">
    * Message bubbles are easier to read
    * The AI sees attachment names and types
    * Clearer phone keypad tones during voice calls
  </Expandable>

  <Expandable title="Fixes">
    * Freshchat handoffs and agent lookup are more reliable
    * Front AI replies no longer accidentally archive conversations
    * Saving Sunshine settings no longer clears your Zendesk connection
  </Expandable>
</Update>

<Update label="May 6, 2026">
  ## From blank workspace to live AI — guided by Companion

  <Frame>
    <img alt="Onboarding panel with three numbered steps: Discover & Train, Go Live, Grow" />
  </Frame>

  Three new flows in Companion: a guided onboarding path, plan-first execution, and live test sessions. Setup to shipped, all in one chat.

  ### Plan first, then act

  <Frame>
    <img alt="Expanded Starting plan with 17 steps: Set up AI Identity, Crawl open.cx, Create folders, Instructions for channels, pricing, security, handoff, and a final Publish step" />
  </Frame>

  Every multi-step ask gets a fully itemized plan up-front. Approve, edit, or stop — Companion never moves on its own.

  * Itemized plan up-front for every substantial ask
  * Live progress counter ticks as steps execute
  * Stop or redirect at any step

  ### Test before you ship

  <Frame>
    <img alt="Companion chat on the left with a Test conversation card; live widget on the right showing the AI replying to a Test Customer" />
  </Frame>

  Spin up a real customer-side widget next to the chat. See exactly how the AI responds, then train where it falls short.

  * Real widget, real AI — same tools, same responses
  * Side-by-side: Companion on the left, Test Customer on the right
  * Companion reads the transcript and recommends concrete fixes

  <Expandable title="Features">
    - Three-step path — Discover & Train, Go Live, Grow — driven by Companion
    - Progress derives from your real workspace state, not checkboxes
    - One panel everywhere — chat, empty inbox, landing page
  </Expandable>
</Update>

<Update label="May 6, 2026">
  ## Group your inbox by channel, assignee, status, language, or team

  Add a Group By to any inbox view and the session list collapses into labelled sections — grouping by channel, assignee, status, AI status, language, or support team. Saved on the view, so the grouping comes back the next time you open it.

  <Expandable title="Features">
    * New Group By control in the filter menu — pick from channel, assignee, status, AI status, language, or support team
    * Group selection is part of the view, so it persists across reloads and across teammates with access to the view
    * Group headers are compact and tighten the spacing between groups so you see more sessions at a glance
  </Expandable>

  <Expandable title="Improvements">
    * Inbox loads more sessions per group when a Group By is active, so you don't see truncated buckets
  </Expandable>
</Update>

<Update label="May 6, 2026">
  ## Saved replies now support variables

  Drop variables (macros) into a saved reply and they fill in from the session at send time — contact name, ticket number, agent name, and more. Edit existing replies and add variables from the same place you create them.

  <Expandable title="Features">
    * Insert variables when authoring a saved reply; they resolve against the active session at send time
    * Saved replies editor refreshed — fixes overflow on long replies and drops slow-loading empty states
  </Expandable>
</Update>

<Update label="May 6, 2026">
  ## Personalize how the inbox sends messages — per channel

  A new Personalization settings page lets each agent pick how they send messages on each channel. Choose Enter or Cmd+Enter as the send shortcut per channel, and the active shortcut shows up right on the send button.

  <Expandable title="Features">
    * New Personalization settings group — per-channel send shortcut preference (Enter or Cmd+Enter)
    * The send button shows the active shortcut inline, so you always see how the next message will be sent
  </Expandable>

  <Expandable title="Improvements">
    * Settings sidebar regrouped — Notifications now lives under a new Personalization section
    * Cleaner shortcut dropdowns: monospace kbd labels, tighter spacing, no redundant separators
  </Expandable>
</Update>

<Update label="May 6, 2026">
  ## Inbox shows messages in the agent's language by default

  Translated messages are now what the agent sees by default — and what the customer sees by default for outbound replies — so you don't need to click into each message to reveal the translation. A "Show original message" action is one click away on every message.

  <Expandable title="Improvements">
    * Bubble renders the translated message by default; one click reveals the original
    * URL previews now match the displayed (translated) text, so the link chips line up with the bubble
  </Expandable>

  <Expandable title="Fixes">
    * Outbound agent replies in the inbox now show the original (workspace-language) version, not the translated one shipped to the customer
  </Expandable>
</Update>

<Update label="May 5, 2026">
  ## Inbox messages send instantly

  Agent replies now render the moment you hit send — no more waiting for the round trip. The optimistic message is reconciled with the server in the background and dedupes cleanly when the real message arrives.

  <Expandable title="Improvements">
    * Agent messages render optimistically and reconcile against the server response — no flicker, no duplicates, no avatar swap
    * Outbound socket payload carries a client-generated UUID for clean dedup
  </Expandable>
</Update>

<Update label="May 5, 2026">
  ## Custom views: drag to reorder, filter by current user

  Drag custom views in the view selector to reorder them — order persists per-org. And every view that filters by assignee can now use a dynamic Current User token, so one shared "My open tickets" view works for the whole team.

  <Expandable title="Features">
    * Drag and drop custom views in the view picker (via a dedicated Reorder dialog) — order is saved per-org
    * New Current User option in the assignee filter — saves a single view that means "assigned to me" for whoever opens it
  </Expandable>

  <Expandable title="Improvements">
    * Team management modal and tab state now sync to the URL — bookmark `/settings/groups?team=<id>&tab=members` and land back on the same screen
  </Expandable>
</Update>

<Update label="May 5, 2026">
  ## Per-channel control over agent assignment on handoff

  Each channel now has its own assign-on-handoff toggle. Hand off in WhatsApp without auto-assigning to an agent while keeping auto-assignment on for email — or vice versa.

  <Expandable title="Features">
    * New per-channel `assign_on_handoff` setting in the rollout strategy modal
    * Handoff service respects the per-channel toggle before auto-assigning
  </Expandable>

  <Expandable title="Fixes">
    * Handoff settings now respect the Web channel config for API and Web Voice channels (instead of silently coupling to a different bucket)
  </Expandable>
</Update>

<Update label="May 5, 2026">
  ## Faster, more accurate voice transcription

  The voice agent pipeline switches to Deepgram Flux for Western languages and Nova 3 for Arabic — a notable accuracy bump on alphanumerics and account-number reads, with lower latency than the previous OpenAI realtime path.

  <Expandable title="Improvements">
    * Deepgram Flux for Western languages, Nova 3 for Arabic — better alphanumeric accuracy and lower latency
    * Flux now runs through LiveKit Inference for unified routing and direct Deepgram fallback
  </Expandable>
</Update>

<Update label="May 5, 2026">
  ## New workflow building blocks

  Five new pieces of workflow plumbing land together: a Contact Message Received trigger, a Reopen Ticket action that walks the official status path, an Apply Custom Status action, a Release Session From Capacity action that frees up an agent slot until the customer replies, and an Inactive Trigger improvement that ignores the workflow's own outbound messages.

  <Expandable title="Features">
    * New Contact Message Received trigger — fires on every inbound contact message with the ticket and message text
    * New Reopen Ticket action — reopens a closed session through the official status path so SLA, system rows, and inactivity timers are correctly inserted
    * New Apply Custom Status action — set a sub-status without changing the main status
    * New Release Session From Capacity action — temporarily frees an agent's capacity slot until the customer replies again
    * Get Ticket Agent action returns nullable fields when there is no assignee, so it no longer throws inside no-assignee branches
    * New `callFinishedBy` field on the Call Finished trigger payload, so workflows can branch on who ended the call
  </Expandable>

  <Expandable title="Improvements">
    * Workflow editor auto-fills canonical action inputs (e.g. ticket number) from the trigger payload at drop time
    * Save validation now reports every missing required action input — Fix-to-jump on each error
    * Action node cards humanize their inputs with one row per field — long values truncate instead of blowing up the card
    * Custom Status / Apply / Release / Reopen actions now clear `sub_status_id` on every status change for consistency
  </Expandable>

  <Expandable title="Fixes">
    * Customer-inactive trigger no longer schedules itself off its own workflow message inserts (no more infinite loops)
    * Customer-inactive trigger no longer arms on AI replies — only on real agent messages and inbound contact messages
  </Expandable>
</Update>

<Update label="May 4, 2026">
  ## Export your AI knowledge base as CSV

  Export your AI Instructions tree as CSV — full export from the section header, or scoped per-folder from any folder's hover menu. Filename includes the folder slug, and a confirm dialog previews the file before download.

  <Expandable title="Features">
    * New Export as CSV action on AI Instructions — full or per-folder, with a preview dialog showing filename, count, and column badges
    * Per-folder export filenames slug the folder name (`ai-instructions-{slug}-YYYY-MM-DD.csv`) so multi-folder dumps don't collide
  </Expandable>
</Update>

<Update label="May 4, 2026">
  ## Smarter, fairer agent distribution

  Agent routing now factors in released-from-capacity sessions as a tiebreaker — agents with fewer paused conversations get the next ticket when capacity is otherwise tied. When agents are completely tied, distribution randomizes instead of always picking the first one.

  <Expandable title="Improvements">
    * Released-from-capacity sessions are excluded from team and global capacity counts until the customer replies again
    * Tiebreaker order: most remaining capacity → fewest released sessions → random pick when fully tied
    * Agent availability picker now searches by `name` (matches the backend DTO) and returns up to 250 agents
  </Expandable>
</Update>

<Update label="May 3, 2026">
  ## FreshChat: AI replies on assignment, lifecycle events, and webhook fixes

  The FreshChat integration now mirrors Intercom — the AI starts replying as soon as a conversation is assigned to it, and lifecycle events (resolution, reopen, assignment) flow through correctly with the right system messages and SLA bookkeeping.

  <Expandable title="Features">
    * AI starts replying on `conversation_assignment` to our agent, replaying any pre-assignment messages
    * Conversation resolution renders as a system event in the timeline (matches the Front integration convention)
    * Conversation reopen flips the OpenCX session back to OPEN, inserts the AGENT\_REOPENED\_SESSION row, and resumes SLA + inactivity timers — across every matching session, not just the first
    * Webhook URL is now copyable from the FreshChat settings page
  </Expandable>

  <Expandable title="Fixes">
    * Workflow Close Ticket action now routes through FreshChatService.closeConversation when a `freshchat_conversation_id` is present, instead of failing with `UNEXPECTED_ERROR`
    * Self-close webhook echo no longer writes a duplicate "Conversation was closed in FreshChat" lifecycle event
    * Webhook action names match the FreshChat docs (`conversation_assignment`, `conversation_resolution`, `conversation_reopen`)
    * Transport errors from `getAgentByEmail` now propagate so FreshChat retries — they no longer silently drop assignment events
  </Expandable>
</Update>

<Update label="May 3, 2026">
  ## Describe your tags so the AI auto-tagger picks the right one

  Add a short description to each tag and the AI auto-tagger uses it as taxonomy guidance — picking the right tag when the name alone is ambiguous.

  <Expandable title="Features">
    * Add an optional one-sentence description when creating or editing a tag
    * Available everywhere you manage tags: the dashboard, the public API, and the @opencx/mcp tools
  </Expandable>

  <Expandable title="Improvements">
    * Tag management page redesigned: rounded pills, hover the tag to see its description, and a confirmation step before deleting
  </Expandable>
</Update>

<Update label="May 3, 2026">
  ## Contact segments in the public API, MCP, and workflows

  Read your contact segments and check membership from anywhere — the public API, the @opencx/mcp tools, or a new workflow action that branches on whether a contact is in a given segment.

  <Expandable title="Features">
    * New public-API endpoints: list segments, get a segment, list every segment a contact is in, and check membership for a (segment, contact) pair — all gated by the contacts:read scope
    * New @opencx/mcp tools wrapping those endpoints: list\_contact\_segments, get\_contact\_segment, list\_segments\_for\_contact, and check\_contact\_in\_segment — available in v1.11.0
    * New "Check Contact In Segment" workflow action with a lazy segment picker; returns isMember so you can branch downstream with an if step
  </Expandable>
</Update>

<Update label="April 30, 2026">
  ## Trigger workflows when human agents go quiet

  <Frame>
    <img alt="Workflow canvas with a Human Agent Inactive trigger connected to an outbound reply action" />
  </Frame>

  A new workflow trigger fires when a human agent hasn't acted on a ticket for a chosen window — minutes, hours, or days. Wire it to any action to auto-reply with a check-in, hand the conversation back to AI, change ticket status, or escalate to a teammate.

  <Expandable title="Features">
    * New "Human Agent Inactive" trigger fires when an assigned human agent hasn't replied for a configurable window
    * Pick the inactivity window in minutes, hours, or days — defaults to 20 minutes
    * Wire it to any action — automated outbound reply, change ticket status, hand back to AI, notify a teammate
  </Expandable>
</Update>

<Update label="April 30, 2026">
  ## Custom email template per address

  <Frame>
    <img alt="Email channel configuration page with Sender Name field and HTML template editor" />
  </Frame>

  Each connected email address now has its own HTML template. Wrap outbound replies in your own branded chrome — header, footer, ticket number, and quoted thread — using a small set of placeholders, configured independently per address.

  <Expandable title="Features">
    * Set a custom HTML template per email address from a new dedicated configuration page
    * Slot in the message body, prior thread, ticket number, and locale with `{{content}}`, `{{quoted_content}}`, `{{ticket_number}}`, and `{{lang}}` placeholders
    * Validation catches a missing `{{content}}` placeholder before the template saves
    * Falls back to a clean default template when none is set — existing addresses keep working untouched
  </Expandable>
</Update>

<Update label="April 19, 2026">
  ## Share custom views with your team

  <Frame>
    <img alt="Custom view dialog with users and teams permission pickers" />
  </Frame>

  Custom views now have permissions. Pick who can see a view — specific users, specific teams, or everyone in the org — and pick who can edit or delete it. Tweaking filters on a saved view keeps the view selected with an "(Unsaved changes)" indicator, so you never lose your place.

  <Expandable title="Features">
    * Share a view with specific users, specific teams, or the whole org
    * Restrict editing and deleting to specific users or teams — the creator can always edit
    * New Save, Save as, and Create actions in the view picker, with a confirmation dialog before overwriting a shared view
    * Edit a view's filters, sorting, and permissions from one dialog
  </Expandable>

  <Expandable title="Improvements">
    * Changing filters on a saved view now keeps the view selected and shows "(Unsaved changes)" instead of dropping you onto a temporary view
    * Unsaved filter edits survive a page reload
    * Edit and delete buttons on views you don't own are disabled with a tooltip explaining why
    * Adding someone as an editor automatically adds them as a viewer
  </Expandable>
</Update>

<Update label="April 18, 2026">
  ## Build advanced session filters

  <Frame>
    <img alt="Advanced session filter builder with AND/OR conditions" />
  </Frame>

  A new filter builder for the inbox — combine any number of conditions with AND/OR groups to slice your sessions exactly how you want. Save the result as a custom view and come back to it with one click.

  <Expandable title="Features">
    * Build filters by stacking clauses — pick a field, an operator, and a value
    * Group clauses with AND/OR to express complex queries that used to require a custom view
    * Filter on channel, assignee, contact, custom data, created date, AI status, tags, and more from one unified menu
    * Save any filter as a custom view and reuse it across the team
  </Expandable>
</Update>

<Update label="April 17, 2026">
  ## Try the widget before you install it

  <Frame>
    <img alt="Widget Playground with live preview and copy-ready snippet" />
  </Frame>

  A new interactive Playground in the docs lets you tune every widget option in a live form and copy a ready-to-paste React or HTML snippet. No install, no dashboard — tweak, preview, copy.

  <Expandable title="Features">
    * Tweak theme, launcher size/offset, first-visit messages, and more in a live form — the widget updates instantly
    * Swap between a React component snippet and an HTML `<script>` snippet, each prefilled with your current settings
    * One-click copy — paste straight into your codebase
    * Launch a full preview in a site-style frame to feel the widget exactly as your customers will
  </Expandable>
</Update>

<Update label="April 16, 2026">
  ## Connect multiple FareHarbor accounts to one org

  Tour operators with multiple locations, brands, or currency accounts can now connect each one as a separate FareHarbor integration. The AI picks the right connection automatically based on what the customer is asking about.

  <Expandable title="Features">
    * Add multiple FareHarbor connections per organization — one per location, brand, or currency account
    * Each connection has its own API keys, default company, and AI action toggles
    * The AI routes bookings to the right connection automatically, asking only when the request is ambiguous
    * Single-connection setups are unchanged — no extra prompts, same behavior as before
  </Expandable>
</Update>

<Update label="April 15, 2026">
  ## See every change Companion makes, right in the chat

  <Frame>
    <img alt="Companion showing artifact cards after editing instructions" />
  </Frame>

  Ask Companion to update your instructions, training scenarios, or documents — and it shows you a card for each change, right in the conversation. Click any card to open and review exactly what was updated. No more guessing what got changed.

  <Expandable title="Features">
    * After Companion edits anything, a card appears in the chat — click it to open and review the change
    * When Companion updates multiple files at once, they appear in a single card with tabs so you can flip between them
    * More tools available to Companion, with clearer descriptions so it picks the right one every time
  </Expandable>

  <Expandable title="Improvements">
    * Smoother loading animations while Companion is working
    * The review toolbar no longer overlaps the Companion chat window
  </Expandable>

  <Expandable title="Fixes">
    * Fixed several actions that were occasionally failing — sending messages, managing team members, fetching workflows, and filtering sessions
    * Companion can now access audit logs
    * Overall reliability improvements — Companion completes tasks more consistently with fewer interruptions
  </Expandable>
</Update>

<Update label="April 12, 2026">
  ## PDF attachments for the AI

  <Frame>
    <img alt="Chat widget with PDF invoice attached and AI answering using the document" />
  </Frame>

  Customers can send PDFs in chat and your AI can use them to answer questions.

  <Expandable title="Features">
    * The AI can read PDFs attached to customer messages, with documents processed for conversation context.
  </Expandable>
</Update>

<Update label="April 9, 2026">
  ## Companion

  A senior support ops expert that lives inside your dashboard. Six specialized skills, 140+ tools, and deep context awareness — all from a single conversation.

  ### A dedicated home for your AI assistant

  <Frame>
    <img alt="Companion dedicated page" />
  </Frame>

  Companion gets its own page with a personalized greeting that adapts to your day. Smart suggestion cards surface exactly what needs attention — automation rate drops, unresolved sessions, knowledge gaps, low CSAT scores — so you always know where to start.

  * Personalized greeting based on your name, time of day, and top priorities
  * Smart suggestion cards that surface automation trends, handoff spikes, and knowledge gaps
  * Recent conversation history in the sidebar for quick context switching

  ### Automation strategist — diagnose performance drops

  <Frame>
    <img alt="Companion analyzing automation rate trends" />
  </Frame>

  Ask "why did automation drop this week?" and get a concrete answer backed by data. Companion analyzes handoff reasons, tracks trends over time, and identifies root causes — whether it's an instruction change, a new topic the AI doesn't know, or an integration error.

  * Real-time automation and handoff analytics with trend detection
  * Root cause analysis — instruction changes, knowledge gaps, integration errors
  * Handoff reason breakdowns with specific session examples
  * Proactive suggestions to improve resolution rates

  ### Training expert — rewrite instructions in chat

  <Frame>
    <img alt="Companion editing AI instructions with inline diff" />
  </Frame>

  Tell Companion what you want to change and it rewrites your AI instructions with inline diffs you can accept or reject. Create new instructions, edit existing ones, manage folders, and publish — all without leaving the conversation. Full version history means you can always roll back.

  * Inline diff mode — see exactly what changed before accepting
  * Create, edit, publish, and unpublish instructions from chat
  * Manage instruction folders and visibility in bulk
  * Full version history with one-click revert on every change

  ### Session investigator — debug any conversation

  <Frame>
    <img alt="Companion investigating a session with debug traces" />
  </Frame>

  Paste a ticket number and Companion pulls the full debug trace — every reasoning step the AI took, every tool it called, every knowledge base article it cited, and exactly why it handed off. No more guessing why the AI said what it said.

  * Full reasoning traces with tool calls, citations, and handoff details
  * Debug any conversation by ticket number or session ID
  * See which knowledge base articles were loaded and ranked
  * Identify platform bugs and instruction gaps proactively

  <Expandable title="Features">
    - 140+ operational tools across sessions, training, analytics, workflows, contacts, and voice
    - Conversation recall — references past sessions so context is never lost
    - Integration troubleshooting for Zendesk, HubSpot, Intercom, Slack, and more
    - Voice agent management — create, test, and configure phone agents from chat
  </Expandable>
</Update>

<Update label="April 8, 2026">
  ## AI Instructions — redesigned

  The training center has been completely rebuilt. A new editor, a new way to organize, and now you can see exactly how each instruction performs — all in one place.

  ### New editor & sidebar

  <Frame>
    <img alt="New AI Instructions editor" />
  </Frame>

  A sidebar tree for organizing instructions by folder, a rich text editor with live preview, and the Agent Identity (formerly AI Profile) now lives here — one place to shape how your AI thinks, speaks, and behaves.

  * Sidebar tree — organize instructions into folders with drag-and-drop
  * Rich text editor with formatting, lists, and inline code
  * Agent Identity moved here — configure name, tone, and personality alongside instructions
  * Published/Draft status in the header with one-click publish
  * Search across all instructions from the sidebar

  ### Instruction-level insights

  <Frame>
    <img alt="Insights tab showing handoffs, sentiment, and reasons" />
  </Frame>

  See how each instruction performs in the real world. The new Insights tab shows handoff count, customer sentiment, handoff reasons, and recent conversations — so you know exactly which instructions need attention.

  * Handoff count per instruction — see how often the AI escalates
  * Customer sentiment breakdown — neutral vs angry
  * Handoff reason analysis — missing knowledge, following instructions, unclear instructions
  * Recent handoffs table with ticket links and timestamps

  ### Sort instructions by handoff impact

  <Frame>
    <img alt="Sort instructions by handoffs with direction and date range" />
  </Frame>

  Find the instructions that cause the most escalations. Sort your entire instruction list by handoff count, filter by date range, and focus your time on what matters most.

  * Sort by handoffs — most or least, your choice
  * Date range filter — see handoff trends for any period
  * Instantly spot which instructions need rewriting

  ### Version history & one-click revert

  <Frame>
    <img alt="Version history with v1, v2, v3 timeline and revert" />
  </Frame>

  Every change to your AI instructions is now tracked. Browse the full version timeline, see who changed what and when, and revert to any previous version with one click.

  * Full version timeline — every publish creates a numbered version
  * See who made each change and when
  * One-click revert to any previous version
  * Active version badge shows which version is live

  ### Bulk folder actions

  Manage AI instructions at scale. Change visibility, publish, or unpublish entire folders at once — no more editing instructions one by one.

  * Bulk publish and unpublish all instructions in a folder
  * Change visibility of an entire folder at once
  * Unpublish individual instruction documents
</Update>

<Update label="April 7, 2026">
  ## Action segment filters, workflow code steps & translation glossary

  Restrict AI actions to specific contact segments, write richer automations with await and fetch in code steps, and control session translations with a custom glossary.

  <Expandable title="Features">
    * Restrict actions to specific contact segments
    * Enable await and fetch in workflow code steps for async operations
    * Append-note action — add workflow notes visible in the agent dashboard
    * Optional authentication for webhook triggers via workflows:trigger scope
    * Translation glossary for session messages with CSV import
    * Attachment support in comment editor
    * Test email functionality in channel configuration
  </Expandable>

  <Expandable title="Improvements">
    * Virtualized workflow run logs for faster performance
    * Reopen workflow-closed sessions when the contact replies
  </Expandable>

  <Expandable title="Fixes">
    * Fix send-webhook body already read error
    * Fix contact-segment filter using correct contact ID
  </Expandable>
</Update>

<Update label="April 6, 2026">
  ## Phone agents run workflows

  <Frame>
    <img alt="Phone agent configuration showing workflow actions and knowledge sources" />
  </Frame>

  Your voice agents just got superpowers. Phone agents can now execute workflow actions mid-call — trigger handoffs, create tickets, look up data — while seeing the full chat history in real time.

  <Expandable title="Features">
    * Phone agents can execute workflow actions during active calls
    * Live chat history visible to phone agents during calls
    * Select which workflows are available as tools for each voice agent
    * Knowledge source selection per agent — attach specific instruction folders
    * Telephony-specific voice activity detection for cleaner call handling
  </Expandable>
</Update>

<Update label="March 19, 2026">
  ## Email templates, contact blocking & voice workflows

  Reusable email templates with variables, language detection, and workflow actions; block contacts across Slack and voice; stronger Confluence sync; Zendesk and HubSpot fixes; voice agents can run workflows and see live chat during calls.

  <Expandable title="Features">
    * Email templates — create, edit, and list templates with rich text, live variable detection, defaults per variable, detected language, and sender domain selection from registered channels
    * Send email template to a contact; map template fields from workflow data; ticket sentiment available in workflow triggers
    * Block contacts by contact ID across channels; enforce blocking on Slack inbound and voice calls; pending team invitations shown in the sidebar and user menu
    * Phone agents can execute workflow actions; live chat history during phone calls; clearer session status for calls; custom SIP headers (X-\*) stored on the session for routing and context
    * Pass custom contact or session data using X-\* headers where supported
  </Expandable>

  <Expandable title="Improvements">
    * Confluence — cursor-based V2 API pagination, separate source per connection, manifest refresh on connect, and Airbyte declarative source version handling for fewer sync failures
    * Shared MentionPicker for @mentions in workflows and knowledge base menus
    * Tooltip on “session assumed resolved” system messages shows the actual resolution reason
  </Expandable>

  <Expandable title="Fixes">
    * Zendesk — required-field auto-fill no longer blocks closing tickets or handoff
    * HubSpot — outbound email no longer adds the support inbox address as a recipient
    * Email template UI — delete confirmation during save, variable badge styling, and form layout
  </Expandable>
</Update>

<Update label="March 16, 2026">
  ## Deep research alerts, help center media, SLA API & Salesforce MIAW

  Notifications when deep research finishes or VOC exports are ready; upload images in the help center; SLA analytics and chat-history context in the API; Salesforce Messaging webhooks; desktop notifications and inbox comment polish.

  <Expandable title="Features">
    * Notifications when a deep research report completes; alerts when a VOC export is ready or your team is assigned to an insight
    * Media library — upload, sync, and embed images in articles from the dashboard editor; store and serve OpenAPI specs for your help center API playground
    * Salesforce Embedded Messaging (MIAW) webhook to replace polling and reduce rate limits; webhook URL available from the dashboard
    * Optional desktop notifications for browser alerts; notification settings page refresh with switches and dark mode; search and keyboard-friendly org switcher
    * Post internal comments with @mentions only; get notified when someone @mentions you (including yourself where enabled); cleaner rendering for mentions and line breaks
    * Sync knowledge base content on fork environments from the fork card; CRM integrations page aligned with the design system
    * Workflow editor header actions align correctly with tabs
    * IP-based authentication for LiveKit inbound trunks; streamlined phones table and number deletion
    * US purchased numbers cannot be toll-free (validation update)
  </Expandable>

  <Expandable title="Improvements">
    * HubSpot email replies send formatted HTML so AI-generated styling is preserved in the customer’s inbox
    * Highlight the selected thread comment alongside the selected message
    * Reference values that include dots in property paths resolve correctly
  </Expandable>

  <Expandable title="Fixes">
    * HubSpot and FreshChat session closure sync run correctly (no longer gated only on Zendesk)
    * SLA analytics — next-reply percentiles, filtered session totals, and reply-time accounting in breakdown and trend endpoints
    * Notification popover shortcut, focus styles, and loading states when fetching more items
  </Expandable>
</Update>

<Update label="March 9, 2026">
  ## Inbox Comments, Notifications & Shopify Integration

  Threaded comments with @mentions in the inbox, a real-time notification center with keyboard navigation, Shopify as a knowledge base data source, and nested help center categories.

  <Expandable title="Features">
    * Threaded comments on inbox messages — discuss conversations internally with your team
    * @mention teammates in comments to notify them directly
    * In-app notification center with real-time delivery, unread counts, and keyboard navigation
    * Shopify integration with OAuth popup, stream selection (pages, articles, products), and knowledge base sync
    * Nested categories with collapsible subcategories in the sidebar
    * Source markdown editor with theme support for article editing
    * Content tree sync API with SSE streaming for CLI-based management
    * CLI authentication flow for help center management
    * Merge contact custom data workflow action
    * Custom User-Agent field for HTTP workflow actions
    * Filter contacts by session attribute key-value pairs in segments
  </Expandable>

  <Expandable title="Improvements">
    * Respect AI instruction restrictions by segment and channel — instructions now correctly apply only to matching contacts and channels
    * Segments UI revamp with infinite scroll and pagination
    * Improved workflow runs UI with loading skeletons and better search
    * Fix Confluence connector by using pages as check stream and v2 API params
  </Expandable>

  <Expandable title="Fixes">
    * Fix Intercom re-sending existing conversation attributes on sync
    * Fix HubSpot replies going to support inbox instead of the customer
    * Re-schedule inactivity workflows when a session is reopened
    * Fix Airbyte data residency field causing errors on self-hosted instances
  </Expandable>
</Update>

<Update label="March 2, 2026">
  ## SLA Policies, Scoped API Keys & Content Checks

  Service level agreements with real-time tracking and breach notifications, fine-grained API key permissions, AI-powered content quality checks for help center articles, and expanded webhook and export coverage.

  <Expandable title="Features">
    * SLA policies with first reply, next reply, and resolution targets — track response times against your commitments
    * SLA snooze/unsnooze to pause timers during customer delays
    * Filter and sort inbox by SLA status and urgency
    * Real-time SLA badge updates with breach and late status indicators
    * SLA workflow triggers for `sla_first_reply_breached`, `sla_next_reply_breached`, and `sla_resolution_breached`
    * AI content check rules — define quality rules with severity levels and validate articles before publishing
    * Icon picker for help center categories
    * Content tree export API for CLI-driven workflows
    * New `csat.score_submitted` webhook event
    * New `csat.requested` webhook event
    * AI context compaction for analyzing large conversation sessions
    * CSAT score and comment columns in session data export
    * Past billing periods with detailed usage breakdowns
    * Bidirectional HubSpot custom data sync
    * Sync HubSpot ticket properties on session creation
    * Sync Zendesk user and organization fields into contact custom data
    * Scoped API keys — assign fine-grained read/write permissions per resource when creating API keys
    * Contact search endpoint with composite filters
  </Expandable>

  <Expandable title="Improvements">
    * Faster workflow run log search using optimized queries
    * Handle office hours shifts where start time is greater than end time
    * Redesigned organization creation page
    * Show custom payload in dashboard when session is closed through API
    * Clean HTML/markdown from outbound Messenger and Instagram text messages
  </Expandable>

  <Expandable title="Fixes">
    * Fix HubSpot not pulling all ticket properties
    * Prevent AI from responding to handed-off Flex sessions
    * Fix hydration error causing inbox page crash on login or org switch
    * Fix export button enabled when session count is zero
    * Preserve article slugs on edit and redirect deprecated slugs
    * Fix workflow trigger crash in sessions resolution job
  </Expandable>
</Update>

<Update label="February 25, 2026">
  ## Workflow & Handoff Webhooks

  <Expandable title="Features">
    * New `workflow.run.succeeded` and `workflow.run.failed` events — subscribe to get notified when workflow runs complete or fail
    * New `conversation.handoff_to_third_party_failed` event — get notified when a third-party handoff (e.g. Zendesk, Intercom) fails to complete
  </Expandable>
</Update>

<Update label="February 23, 2026">
  ## Help Center Customization & Voice Recording

  Major help center customization options, new crawl public API, built-in voice session recording, and reliability improvements across workflows and integrations.

  <Expandable title="Features">
    * Custom CSS and head scripts with a dedicated help center settings route
    * Help center public APIs with service authentication, search, and scoped article access
    * Built-in LiveKit voice session recording
    * Default new organizations to AI agent v2 across all channels
    * Invitation role support with role-based assignments
    * Enable handoff outside office hours for email channel
  </Expandable>

  <Expandable title="Improvements">
    * Improve call forwarding and inbound voice routing reliability
    * Include contact custom data in workflow payloads with safer empty-contact handling
    * Improve Zendesk AI field auto-fill transcript quality by including AI action context
    * Improve workflow run log performance and status filtering
    * Sync session custom data to HubSpot tickets
    * Improve help center editor and sidebar UX
  </Expandable>

  <Expandable title="Fixes">
    * Auto-publish translations that complete after article publish
    * Fix spacebar input handling in workflow fields
    * Fix clickable handoff popover title behavior
    * Fix Freshchat contact email conflict on backfill
    * Fix Zendesk language tag assignment on error handoff
    * Fix HubSpot contact search parsing
  </Expandable>
</Update>

<Update label="February 16, 2026">
  ## Image Uploads, Handoff Insights & Web Crawler v2

  Help center now supports image uploads and article cross-referencing. New handoff analytics, web crawler v2 with scheduled jobs, and OpenAPI tool validation before import.

  <Expandable title="Features">
    * Image upload with alt text editing in help center editor
    * Article reference linking with `[[` suggestion
    * Handoff event tracking and analytics
    * Validate OpenAPI tools with OpenAI before import
    * Web crawler v2 with BullMQ scheduled jobs replacing polling
    * Phone agent training with knowledge source selection
  </Expandable>

  <Expandable title="Improvements">
    * Add Team/Group column to insights CSV export
    * Cap VoC batch processing at 20 per run for stability
    * Session export UX improvements — friendly filename and file size display
    * Bulk delete for knowledge base folders
    * Export CSV for knowledge base folders
    * Edit action tags directly in the UI
    * Poll for session export status instead of relying on socket events
  </Expandable>

  <Expandable title="Fixes">
    * Use organization timezone for date prompt in AI system messages
    * Fix VoC category classification accuracy
    * Fix occurrence count with active date filters
    * Fix end-of-day handling for date-only filters
    * Fix updating and deleting custom office hours
    * Fix Freshdesk sync mode and start\_date format for Airbyte
    * Fix Airbyte embedding sync race condition with webhook approach
  </Expandable>
</Update>

<Update label="February 9, 2026">
  ## Voice Agents with SIP, FareHarbor & Server-Side Data Export

  Full TypeScript-based LiveKit voice agents with SIP trunk integration for inbound and outbound calls, FareHarbor booking integration, revamped data export with server-side processing, and Freshdesk integration.

  <Expandable title="Features">
    * LiveKit voice agent rewritten in TypeScript with SIP trunk support for inbound and outbound calls
    * SIP inbound trunk configuration and phone number routing UI
    * Phone agent creation UX with version selection modal
    * FareHarbor integration with payment link generation and SMS actions
    * Server-side data export with column configuration and export history
    * Freshdesk integration for ticket syncing via Airbyte
    * Custom analytics dashboards with Metabase integration
    * Help center public API endpoints and settings dialog
    * Auto-create run when activating one-off sequences
  </Expandable>

  <Expandable title="Improvements">
    * Background audio feedback during agent processing
    * Quicker recording setup and improved inactivity handling
    * Improved SIP setup UI and inbound trunk management
    * Record sequence run events (queued, sent, failed, completed, canceled)
    * Skip email for unsubscribed contacts
    * Help center domain validation with CNAME instructions
  </Expandable>

  <Expandable title="Fixes">
    * Fix inbound phone agent routing
    * Fix contact phone number filtering
  </Expandable>
</Update>

<Update label="January 29, 2026">
  ## Saved Reply Variables

  Major updates to the help center with improved translation workflow, enhanced saved replies editor with variable support, and better AI agent capabilities. Includes performance improvements and UI refinements across the platform.

  <Expandable title="Features">
    * AI agents can now see external attachments from integrations in chat history
    * Saved replies editor with variable support for dynamic content
    * Help center revamp with improved translation workflow and version management
    * Chat history search functionality
    * Session auto distribution triggers for better conversation routing
    * Custom translation prompts for help center content
  </Expandable>

  <Expandable title="Improvements">
    * Translation status indicators show when content is being translated
    * Category translations now complete synchronously for immediate feedback
    * Auto-create draft versions when updating published articles
    * Updated terminology from "Activate/Deactivate" to "Publish/Unpublish" for clarity
    * Session distribution calls now run in parallel for better performance
    * Faster data refresh intervals for real-time updates
    * UI improvements including updated border radius, sidebar styling, and keyboard shortcuts
  </Expandable>

  <Expandable title="Fixes">
    * Fixed translation flickering in help center
    * Breadcrumb navigation now properly blocks when articles have unsaved changes
  </Expandable>
</Update>

<Update label="January 26, 2026">
  ## Zendesk Auto-Fill on Ticket Closure

  When closing Zendesk tickets, the AI now automatically fills required custom fields. Includes Slack notifications and internal notes for closed tickets, ensuring all necessary information is captured before resolution.
</Update>

<Update label="January 25, 2026">
  ## WhatsApp Multi-Line Messages

  Messages sent through WhatsApp now preserve line breaks properly. Multi-line messages display as intended, improving readability for customers. Better handling of leads and visitors in Intercom. Contact details are now fetched more reliably using multiple identifiers, with proper fallback to email addresses when webhook data is incomplete.
</Update>

<Update label="January 24, 2026">
  ## Knowledge Base Filters

  Add filters to your knowledge base semantic search. Narrow down results based on metadata to find the most relevant content faster. New analytics dashboard for handoff events with filtering options. Track handoff reasons, view reason combinations, and analyze patterns to optimize your support workflow. When rejecting suggested insight categories, you can now specify a fallback category. This ensures insights are always properly categorized, improving organization and analysis.
</Update>

<Update label="January 17, 2026">
  ## Role-Based Access Control

  Comprehensive role management system with custom roles and permissions. Define granular access controls for your team members and manage user permissions at scale. Configure how conversations are distributed within teams. Set custom assignment strategies and max session limits per team member to balance workload effectively.
</Update>

<Update label="January 16, 2026">
  ## Auto-Assign Group Action

  Automatically assign conversations to specific support groups based on workflow conditions. Configure fallback groups to ensure tickets are always routed properly.
</Update>

<Update label="January 15, 2026">
  ## Filter Insights by Team Assignment

  Filter customer insights by assigned or unassigned teams. Quickly find insights that need team assignment or review those already being handled. Improved reliability when syncing data with HubSpot, especially for customers on lower plans who may hit rate limits.
</Update>

<Update label="January 14, 2026">
  ## Faster Workflow Run Logs

  Workflow run logs are now significantly faster. View detailed execution history for all your workflows with improved performance.
</Update>

<Update label="January 13, 2026">
  ## Agent Handoff Controls

  Enhanced handoff settings that respect your availability configuration. Prevent handoffs when turned off in settings, ensuring AI continues handling conversations.
</Update>

<Update label="January 12, 2026">
  ## Enhanced Insight Comments

  Insight comments now support reactions and read tracking. See who has viewed your comments and engage with team feedback using emoji reactions. Each customer insight now has a unique sequential number for easier reference and tracking. Quickly identify and reference specific insights across your team. Configurable wait time before fetching Intercom conversation custom attributes. Ensure all custom data is collected before processing conversations. Filter chat sessions by team IDs in the API. Retrieve conversations assigned to specific support teams.
</Update>

<Update label="January 11, 2026">
  ## Front Integration

  Fetch article content from Front knowledge base. Integrate your Front help center content into your AI's knowledge base.
</Update>

<Update label="January 10, 2026">
  ## Multiple Inboxes

  Organize conversations across multiple inboxes. Route and manage different types of conversations in separate inboxes based on channel, team, or your own criteria. Assign different office hours to individual teams. Each support group can now have its own availability schedule and assignment rules. New workflow action to retrieve custom office hours and check if the current time falls within them. Make routing decisions based on team-specific availability.
</Update>

<Update label="January 9, 2026">
  ## Enhanced Zendesk Agent Control

  Improved handling of Zendesk handoffs. When Zendesk agents reassign conversations back to the AI, control is automatically passed back to ensure seamless transitions. Enhanced Twilio Flex integration with better task management, improved logging, and support for custom first messages. Conversations close properly when tasks are resolved.
</Update>

<Update label="January 8, 2026">
  ## Prohibited Topic Detection

  New system messages when prohibited topics are detected, including the reasoning behind the detection. Provides transparency in AI safety controls. Improved AI accuracy with reranking for both organization knowledge base and custom instructions. The AI now prioritizes the most relevant information when responding. Full-text search capabilities for workflow run logs. Quickly find specific workflow executions by searching through log content.
</Update>

<Update label="January 7, 2026">
  ## Zendesk Audit Logs

  Access Zendesk audit logs to track ticket changes and agent actions. Better visibility into ticket history and modifications. Enhanced customer insight generation with better quality controls and filtering. The system now prioritizes generating high-quality, actionable insights. Improved error handling and automatic retries across AI operations. Better resilience when handling timeouts and unexpected errors. The AI now includes whitelisted session and contact custom data in its context. Configure which custom attributes the AI should consider when responding to customers.
</Update>

<Update label="January 6, 2026">
  ## Enhanced Customer Insights Processing

  Significant performance improvements to customer insights analysis. Faster processing of session insights with optimized batch operations. Enhanced attachment handling with presigned URLs for better security and performance when the AI processes file attachments.
</Update>

<Update label="January 5, 2026">
  ## Session Sentiment in API

  Session sentiment and AI closure type are now included when retrieving sessions through the public API. Better visibility into conversation outcomes. Enhanced contact details view with more comprehensive information. Get a complete picture of each contact's history and interactions.
</Update>

<Update label="January 4, 2026">
  ## Filter by Ticket Custom Data

  Filter sessions by custom ticket data fields. Find conversations based on any custom metadata you've stored on tickets. Filter customer insights by session language. Analyze feedback from specific language groups separately. New workflow action to check if the current time is within default working hours. Make scheduling decisions in your automations.
</Update>

<Update label="January 3, 2026">
  ## Prohibited Topic Workflow Trigger

  Trigger workflows automatically when prohibited topics are detected. Take custom actions like notifying supervisors or escalating conversations. Connect Front to Open.cx for AI-powered support. Handle conversations from Front with seamless integration for message sending and conversation management.
</Update>

<Update label="January 2, 2026">
  ## Next-Generation AI Agent (V5)

  New AI agent architecture with improved reasoning capabilities and better performance. Enhanced conversation handling with more accurate responses.
</Update>

<Update label="January 1, 2026">
  ## Office Hours V2

  Redesigned office hours system with improved flexibility and performance. Better management of team availability across multiple timezones.
</Update>

<Update label="December 31, 2025">
  ## AI Closure Type Filter

  Filter chat sessions by AI closure type. Analyze how the AI resolved conversations and identify patterns in automated resolutions.
</Update>

<Update label="December 30, 2025">
  ## Faster Inbox & Search

  Significant performance improvements to inbox sessions loading and search (contacts and messages).
</Update>

<Update label="December 15, 2025">
  ## Saved Replies

  Create and reuse pre-written responses for common questions. Saved replies help agents respond faster while maintaining consistent messaging across your team.
</Update>

<Update label="December 14, 2025">
  ## Agent Availability

  Simplified agent availability with a clear on/off toggle and custom status messages. Agents can now set a custom status to let their team know what they're working on while indicating their availability for new conversations.
</Update>

<Update label="December 11, 2025">
  ## WhatsApp Interactive Lists

  When the AI has more than 3 suggestions to offer, they now appear as an interactive list in WhatsApp. This provides a cleaner experience for customers navigating multiple options.
</Update>

<Update label="December 9, 2025">
  ## Pre-Handoff Workflow Trigger

  Trigger a workflow right before a conversation is handed off to a human agent. Use this to gather additional context, update CRM records, or prepare the agent with relevant information before they take over.
</Update>

<Update label="November 29, 2025">
  ## Workflow Versioning

  Create, update, and manage multiple versions of your workflows. Enable or disable specific versions, making it easy to iterate on your automations without losing previous configurations. Roll back to earlier versions or test new changes before going live.
</Update>

<Update label="November 2, 2025">
  ## Knowledge Gap Detection

  Automatically identify topics where your knowledge base is lacking. Based on real customer conversations, the Customer Insights feature now detects gaps in your documentation, helping you understand what content to add.
</Update>

<Update label="October 27, 2025">
  ## Quick Reply Suggestions

  Actions can now automatically generate quick reply suggestions for certain channels.
</Update>

<Update label="October 23, 2025">
  ## Custom Session Statuses

  Create custom sub-statuses for your sessions beyond the default open/resolved states. Track conversations through your own workflow stages like "Waiting for customer", "Escalated", or "Pending review".
</Update>

<Update label="October 20, 2025">
  ## Session Tag Filter

  Filter your inbox by tags to quickly find related conversations.
</Update>

<Update label="October 15, 2025">
  ## Facebook Messenger Channel

  Connect Facebook Messenger to Open through Zendesk Sunshine. Your AI assistant can now handle conversations from Facebook alongside your other channels.
</Update>

<Update label="October 9, 2025">
  ## Waiting On Filter

  Filter sessions by who they're waiting on — customer, agent, or AI. Quickly identify conversations that need attention and prioritize your queue accordingly.
</Update>

<Update label="October 8, 2025">
  ## WhatsApp Audio Messages

  The AI can now process audio messages from WhatsApp.
</Update>

<Update label="October 5, 2025">
  ## Update Global Variables Action

  Modify your organization's global variables from within workflows.
</Update>

<Update label="October 3, 2025">
  ## Create Zendesk Ticket Action

  Create Zendesk tickets directly from workflows with full control over ticket fields, tags, and assignees.
</Update>

<Update label="September 21, 2025">
  ## Update Pipedrive Lead Action

  Update leads in Pipedrive directly from your workflows.
</Update>

<Update label="September 20, 2025">
  ## Facebook Messenger Channel

  Connect Facebook Messenger pages to Open. Your AI assistant can now handle conversations from Messenger alongside your other channels.
</Update>

<Update label="September 16, 2025">
  ## Instagram Channel

  Connect Instagram business accounts to Open. Handle DMs from Instagram with the same AI-powered support as your other channels.
</Update>

<Update label="September 14, 2025">
  ## Restrict AI Instructions by Segment or Channel

  Limit specific AI instructions to certain contact segments or channels. Provide tailored responses for VIP customers, specific regions, or different support channels.
</Update>

<Update label="September 11, 2025">
  ## Conversation Closed Webhook

  Receive webhooks when conversations are closed. Integrate with external systems to trigger follow-up actions or sync conversation data.
</Update>

<Update label="September 10, 2025">
  ## Require Contact Info on Handoff

  Configure handoff to require name and email before transferring to a human agent. Ensure agents always have the contact information they need.
</Update>

<Update label="September 9, 2025">
  ## Source Email Filter

  Filter your inbox by the email address conversations originated from. Useful for teams managing multiple support addresses.
</Update>

<Update label="September 4, 2025">
  ## Handoff Webhook

  Receive webhooks when conversations are handed off to human agents. Trigger external workflows or notifications when handoffs occur.
</Update>

<Update label="September 2, 2025">
  ## Contact Segments

  Create dynamic contact segments based on attributes, tags, or custom data.
</Update>

<Update label="September 1, 2025">
  ## CSAT Score Trigger

  Trigger CSAT surveys from within workflows.
</Update>

<Update label="August 24, 2025">
  ## Zendesk AI Field Auto-Fill

  AI automatically fills custom Zendesk ticket fields when handing off conversations.
</Update>

<Update label="August 19, 2025">
  ## Custom Session Views

  Create and save custom filtered views of your inbox. Organize your AI training content into folders. Keep instructions organized by topic, product, or team for easier management.
</Update>

<Update label="August 17, 2025">
  ## Widget CSAT

  Collect customer satisfaction scores directly in the chat widget after conversations resolve.
</Update>

<Update label="August 16, 2025">
  ## FreshChat Integration

  Connect FreshChat to Open for AI-powered support. Handle conversations, handoff to agents, and sync resolution status.
</Update>

<Update label="August 12, 2025">
  ## Close Ticket Action

  Close tickets from workflows. Automatically resolve conversations based on conditions or customer confirmation. Trigger message sequences from workflows. Send automated follow-up messages or onboarding flows based on conversation outcomes.
</Update>

<Update label="August 9, 2025">
  ## HubSpot Integration

  Connect HubSpot to Open for AI-powered support on tickets. Handle conversations from HubSpot with the same AI capabilities as your other channels.
</Update>

<Update label="August 5, 2025">
  ## AI Transcription

  Automatically transcribe audio messages. Voice messages from customers are converted to text for AI processing and agent review.
</Update>

<Update label="July 20, 2025">
  ## Twilio Flex Integration

  Connect Twilio Flex to Open.cx. Route conversations to your Flex contact center with AI handling and seamless handoffs.
</Update>

<Update label="July 13, 2025">
  ## Ticket Inactive Trigger

  Trigger workflows when tickets have been inactive for a specified time. Automate follow-ups or escalations for stale conversations.
</Update>

<Update label="July 9, 2025">
  ## Blocked Domains

  Block emails from specific domains. Prevent spam or unwanted messages from reaching your inbox.
</Update>

<Update label="July 8, 2025">
  ## New Contact Trigger

  Trigger workflows when new contacts are created. Automate onboarding sequences or sync contacts to external systems.
</Update>

<Update label="July 5, 2025">
  ## Add Contact Action

  Create new contacts directly from workflows. Capture customer information and add them to your contact list automatically.
</Update>

<Update label="July 3, 2025">
  ## Form Submit Trigger

  Trigger workflows from form submissions. Connect your forms to automations for lead capture, support requests, or data collection.
</Update>

<Update label="July 2, 2025">
  ## Webhook Trigger

  Trigger workflows from external webhooks. Connect any system that can send HTTP requests to your Open.cx automations.
</Update>

<Update label="July 1, 2025">
  ## Workflow Rerun

  Rerun failed workflows with a single click. Debug issues and retry automations without recreating the trigger conditions.
</Update>

<Update label="June 30, 2025">
  ## Customer Insight Categories

  Organize and categorize customer insights. Group related feedback to identify patterns and prioritize improvements.
</Update>

<Update label="June 29, 2025">
  ## Customer Insights Search

  Search through customer insights by keyword. Quickly find specific feedback or themes across all your customer conversations. Show a typing indicator in WhatsApp while the AI is processing a response. Customers see that their message is being handled.
</Update>

<Update label="June 27, 2025">
  ## Run Code Action

  Execute custom JavaScript code in your workflows. Transform data, perform calculations, or implement custom logic.
</Update>

<Update label="June 24, 2025">
  ## Deep Research for Insights

  Generate comprehensive research reports from customer insights. Dive deeper into trends and get actionable recommendations.
</Update>

<Update label="June 16, 2025">
  ## Ask AI About Data Action

  Query AI with structured data in workflows. Pass JSON data and ask questions to extract insights or make decisions. Trigger workflows when phone calls start or finish. Automate follow-ups, logging, or notifications based on call events.
</Update>

<Update label="June 14, 2025">
  ## Manual Trigger with Payload

  Trigger workflows manually with custom data. Test automations or trigger one-off runs with specific payloads.
</Update>

<Update label="June 12, 2025">
  ## Sync Tags to Integrations

  Automatically sync session tags to Intercom and Zendesk. Keep your tags consistent across platforms.
</Update>

<Update label="June 11, 2025">
  ## Team Assignment

  Assign conversations to teams. Route tickets to the right group based on topic, language, or custom rules.
</Update>

<Update label="June 6, 2025">
  ## Translation Settings

  Configure real-time translation settings for your AI. Control which languages are translated and how. Set different office hours for different languages. Provide availability based on your team's language coverage.
</Update>

<Update label="June 1, 2025">
  ## Blocked Contacts

  Block specific contacts from reaching your inbox. Prevent spam or unwanted messages from known bad actors.
</Update>

<Update label="May 25, 2025">
  ## Snooze Customer Insights

  Snooze customer insights to review later. Keep your insights queue focused on what needs attention now.
</Update>

<Update label="May 21, 2025">
  ## Comments on Insights

  Add comments to customer insights and recommendations. Collaborate with your team on how to address feedback.
</Update>

<Update label="May 18, 2025">
  ## AI-Triggered Workflows

  The AI can now trigger workflows during conversations with customers. Automate actions based on what the AI learns from the conversation.
</Update>

<Update label="May 17, 2025">
  ## Salesforce Integration

  Connect Salesforce to Open.cx for case management. Create, update, and sync cases with your Salesforce instance. New workflow steps to ask AI questions about data or the current session. Make intelligent decisions in your automations.
</Update>

<Update label="May 10, 2025">
  ## Outbound Phone Calls

  Make outbound phone calls from the API. Proactively reach out to customers with AI-powered voice calls.
</Update>

<Update label="May 6, 2025">
  ## Workflow Outbound Actions

  New workflow actions to send Slack messages, emails, and webhooks. Plus actions to close sessions and change assignees.
</Update>

<Update label="May 5, 2025">
  ## Intercom Attachments

  Process file attachments from Intercom conversations. Images and files are now handled alongside text messages.
</Update>

<Update label="April 29, 2025">
  ## WhatsApp Public API

  Send WhatsApp templates programmatically through our public API.
</Update>

<Update label="April 24, 2025">
  ## Session Date Filters

  Filter sessions by date range in the API. Query conversations from specific time periods. Filter sessions by contact custom data fields. Find conversations based on any custom attribute you've stored.
</Update>

<Update label="April 13, 2025">
  ## WhatsApp in Sequences

  Include WhatsApp messages in your automated sequences. Reach customers on WhatsApp as part of multi-channel flows. Filter reports by session tags. Analyze performance for specific conversation types or categories.
</Update>

<Update label="April 6, 2025">
  ## Training Public API

  Manage AI training content through the public API. Create, update, and delete training programmatically.
</Update>

<Update label="April 5, 2025">
  ## WhatsApp Location Messages

  Receive and process location messages from WhatsApp. Customers can share their location in conversations.
</Update>

<Update label="March 30, 2025">
  ## Auto-Resolve Sessions

  Automatically resolve WhatsApp and email sessions after 24 hours of inactivity. Keep your inbox clean without manual intervention.
</Update>

<Update label="March 29, 2025">
  ## Agent Availability

  Track agent availability status across your team. See who's online, offline, or busy at a glance.
</Update>

<Update label="March 25, 2025">
  ## Contact Search by Insight

  Search contacts by insight description using natural language. Find customers related to specific feedback themes.
</Update>

<Update label="March 22, 2025">
  ## Handoff Outside Office Hours

  Configure whether to allow handoffs outside office hours. Control how conversations are routed when your team is unavailable. New reporting endpoints for agent performance metrics. Track response times, resolution rates, and CSAT by agent. Send and receive media messages on WhatsApp. Images, documents, and files are now fully supported.
</Update>

<Update label="February 25, 2025">
  ## Team Resolution Stats

  Track resolution statistics by team. See how each team contributes to customer insights.
</Update>

<Update label="February 24, 2025">
  ## Customer Insight Clustering

  Automatic clustering of customer insights using AI and vector similarity. Related feedback is grouped together.
</Update>

<Update label="February 22, 2025">
  ## Team Handoff Reports

  Daily handoff statistics by team. Track how conversations are distributed across your support teams. Filter knowledge base items by custom properties. Find content based on metadata you've added.
</Update>

<Update label="February 20, 2025">
  ## Intercom Integration

  Full Intercom integration with conversation management, handoff support, and team assignment. Trigger workflows on a schedule using cron expressions. Automate recurring tasks and reports.
</Update>

<Update label="January 30, 2025">
  ## Wait Step

  Add wait steps to workflows. Pause execution for a specified duration before continuing to the next step.
</Update>

<Update label="January 29, 2025">
  ## Website Crawling

  Crawl websites to build your knowledge base automatically. Import content from your help center or documentation site.
</Update>

<Update label="January 25, 2025">
  ## Widget User Sessions

  Users can view their conversation history in the widget. Previous sessions are accessible for reference.
</Update>


# Connect AI Supervisor
Source: https://docs.open.cx/connect/ai-supervisor

The AI participant in every Connect thread: answers order questions instantly, translates live, nudges silent parties, masks unsafe content, and escalates to your inbox.

Every Connect thread has a fourth participant: the **Supervisor** — the same AI agent that runs your OpenCX support, with the same [Knowledge](/knowledge/introduction), the same [Actions](/actions/introduction), and the same [handoff rules](/handoff/introduction). It reads every lane and acts on what it sees.

This is the difference between chat infrastructure and Connect. A chat pipe moves messages between three people and stops there. The Supervisor makes the conversation *resolve*.

## Three modes, set per lane

| Mode | The Supervisor will… | Use it for |
| - | - | - |
| `observe` | Watch silently: sentiment, safety masking, analytics, escalation triggers. Never speaks. | Lanes where you only want a safety net |
| `assist` | Everything in observe, plus live translation, suggested replies for merchants and couriers, and unanswered-message nudges. | Keeping humans fast without AI speaking to customers |
| `resolve` | Everything in assist, plus answering directly: order status, ETAs, policies, anything your Actions can do. **Default.** | Absorbing the traffic that shouldn't interrupt anyone |

Set org defaults in **Connect → Supervisor**, override per thread or per lane at [creation](/api-reference/connect/create-thread) or any time with a [PATCH](/api-reference/connect/update-thread). [Autopilot topic rules](/handoff/topics) apply — topics you've gated to humans stay with humans in Connect too.

## What intervention looks like

```mermaid theme={"dark"}
sequenceDiagram
  autonumber
  participant C as Customer
  participant S as AI Supervisor
  participant M as Merchant
  participant H as Your inbox
  C->>M: "وين طلبي؟" (where's my order?)
  S->>C: Courier picked it up 4 min ago — about 12 min away 🛵
  Note over S,M: Merchant never interrupted
  C->>M: "You forgot the garlic sauce. Again."
  S-->>M: Suggested reply + sentiment flag (frustrated, repeat issue)
  M--xS: No reply for 5 minutes
  S->>M: Nudge: customer waiting on customer_merchant lane
  M--xS: Still no reply
  S->>H: Escalate → session with thread summary attached
```

### Answers before anyone is interrupted

In `resolve` mode the Supervisor fields the questions that dominate order chat — *where is my order, how long, can I change the address, what's the refund policy* — grounded in the thread's `order_status`, your `custom_data`, your Knowledge, and live calls to your Actions (track shipment, check refund eligibility, modify delivery notes). Merchants cook, couriers drive, customers get answers in seconds.

### Live translation

Each participant sets a `language`. The Supervisor renders every message in the reader's language — the Arabic-speaking customer and the English-speaking courier each see a native conversation, with the original a tap away. No configuration, no per-message API calls, no translation add-on tier.

### Nudges and cover

Delivery chat dies when one side goes quiet. The Supervisor tracks per-lane response times: after a configurable silence (default 5 minutes) it nudges the silent party, and in `resolve` mode it covers where it can — "The store hasn't replied yet; I checked your order and the kitchen marked it ready 2 minutes ago."

### Safety, always on

In every mode, including `observe`:

* **PII masking** — phone numbers, emails, payment details typed into a lane are masked before delivery.
* **Abuse filtering** — harassment and profanity handled by AI moderation, not wordlists; incidents logged per participant.
* **Off-platform detection** — "call me on +974…" or "pay me cash directly and I'll cancel the fee" gets masked and flagged to you via [webhook](/connect/webhooks).

### Escalation into your real support

When the Supervisor hits its limits — frustrated customer, prohibited topic, explicit "I want a human", or a nudge chain that went nowhere — it escalates: a standard OpenCX [session](/api-reference/chat-sessions/index) opens in your inbox, carrying a summary of the thread, the sentiment trail, and the order context. Your agents handle it with your normal routing, SLAs, and [helpdesk sync](/integrations/introduction) — Connect is a channel in your support stack, not a second stack.

## Configuration

```json theme={"dark"}
{
  "supervisor": {
    "mode": "resolve",
    "lanes": {
      "customer_merchant": { "mode": "resolve", "nudge_after_seconds": 300 },
      "customer_courier": { "mode": "assist" }
    },
    "escalation": {
      "sentiment_threshold": "frustrated",
      "on_unanswered_nudges": 2
    }
  }
}
```

Everything here has a dashboard equivalent under **Connect → Supervisor**, where you'll also find per-lane analytics: resolution rate, deflected messages, translation volume, nudge outcomes, and escalation reasons — the same [Insights](/features) pipeline as the rest of OpenCX.

<CardGroup>
  <Card title="Threads and lanes" icon="layer-group" href="/connect/threads">
    The conversation model the Supervisor operates on.
  </Card>

  <Card title="Connect webhooks" icon="globe" href="/connect/webhooks">
    Every intervention and escalation, streamed to your backend.
  </Card>
</CardGroup>


# Connect overview
Source: https://docs.open.cx/connect/introduction

In-app chat between buyers, sellers, and couriers — with an AI in every conversation that answers, translates, and calls in your team when needed.

**Connect** puts the parties of a transaction — buyer and seller, customer and merchant, and the courier in between — into one conversation: scoped to a single order, booking, or listing, rendered inside your own apps, and supervised by the same AI agent that already runs your support.

One API call when the transaction starts. Everything else — who can talk to whom, translation between them, answering "where's my order?" before a human ever types, closing the thread when the transaction completes — is handled for you.

<Note>
  **[TicketSwap](https://www.open.cx/customer-stories/ticketswap)** mediates buyer↔seller conversations for **19 million fans** with Connect — the AI Supervisor sits between the two sides of every resale, answers the questions neither party should carry, and steps in before a dispute becomes a ticket. Read the [customer story](https://www.open.cx/customer-stories/ticketswap).
</Note>

```mermaid theme={"dark"}
flowchart LR
  subgraph T["Thread · order_84421"]
    AI(("AI Supervisor"))
    C["Customer"] <--> AI
    M["Merchant"] <--> AI
    D["Courier"] <--> AI
    C <-.-> M
    C <-.-> D
  end
  AI -- "escalation" --> H["Your support inbox"]
```

## Why teams pick Connect over a chat SDK

Chat infrastructure vendors sell you channels. You still build the hard part yourself: creating a channel per order, inviting the right people at the right moment, tearing it down after delivery, wiring moderation, bolting a helpdesk on the side — and the conversations themselves stay dumb. Nobody answers, nobody translates, nobody notices the customer is about to churn.

Connect ships the whole transaction workflow as the product:

| | Chat infrastructure | OpenCX Connect |
| - | - | - |
| Conversation model | Channels you orchestrate per order, per pair | One **thread** per transaction, roles built in |
| Lifecycle | You freeze/delete channels from your backend | Follows the transaction status automatically |
| Who talks to whom | Separate 1:1 channels you manage | **Lanes** with per-role visibility |
| Translation | Paid add-on, per-message API calls | Built in, per participant's language |
| "Where's my order?" | Merchant or courier types the answer | AI answers instantly from your Actions |
| Unanswered messages | Nothing happens | AI nudges, then covers for the silent party |
| Escalation to support | Separate desk product + integration work | Native — a thread escalates into a normal OpenCX session |
| Safety | Wordlist filters you configure | AI moderation: PII masking, abuse, off-platform detection |

## The three pieces

<CardGroup>
  <Card title="Threads" icon="layer-group" href="/connect/threads">
    A transaction-scoped conversation with roles, lanes, and a lifecycle that mirrors the transaction — open, locked, archived.
  </Card>

  <Card title="AI Supervisor" icon="shield-halved" href="/connect/ai-supervisor">
    Watches every lane. Answers instantly, translates live, nudges silent parties, masks unsafe content, escalates to your team.
  </Card>

  <Card title="Drop-in UI or headless API" icon="code" href="/connect/quickstart">
    A prebuilt thread component for your customer, merchant, and courier apps — or raw REST + webhooks if you own the UI.
  </Card>
</CardGroup>

## What teams run on Connect

The same thread model fits any transaction with two or three parties — use the roles that match your marketplace and skip the ones that don't:

* **Marketplace resale** — buyer↔seller mediation on every listing: "is it still available?", payment-safety nudges, dispute de-escalation, and an AI that masks off-platform contact attempts. (This is TicketSwap's shape: two roles, no courier.)
* **On-demand delivery** — the three-touchpoint order: customer↔merchant for "no onions please", customer↔courier for "gate code is 4411", and the AI absorbing order status, ETAs, and refund questions from your Knowledge and [Actions](/actions/introduction) before anyone is interrupted.
* **Bookings and services** — guest↔host, client↔provider: pre-appointment questions, reschedules answered from your calendar Actions, and post-service issues caught while they're still small.

Whatever the shape, **your support team stays in one inbox.** When a thread needs a human, it escalates into a standard OpenCX [session](/api-reference/chat-sessions/index) with the full thread context attached — same inbox, same handoff rules, same analytics as every other channel.

## Where to next

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/connect/quickstart">
    Order chat live in your app in about fifteen minutes.
  </Card>

  <Card title="Connect API reference" icon="code" href="/api-reference/connect/index">
    Threads, participants, messages, tokens — the full REST surface.
  </Card>
</CardGroup>


# Connect quickstart
Source: https://docs.open.cx/connect/quickstart

Ship customer–merchant–courier chat in your app in about fifteen minutes: create a thread per order, add the courier, drop in the UI, let order status drive the rest.

By the end of this page an order in your system has a live conversation between its customer, merchant, and courier — with the AI Supervisor already answering the questions none of them should have to.

Everything below uses your normal [API key](/api-reference/authentication).

```mermaid theme={"dark"}
sequenceDiagram
  autonumber
  participant You as Your backend
  participant CX as OpenCX
  You->>CX: POST /connect/threads (order confirmed)
  CX-->>You: thread th_9f2c4e · customer↔merchant lane open
  You->>CX: POST /threads/th_9f2c4e/participants (courier assigned)
  CX-->>You: customer↔courier lane open
  Note over CX: Participants chat · AI answers, translates, nudges
  You->>CX: PATCH /threads/th_9f2c4e { order_status: "delivered" }
  CX-->>You: thread locks itself after the grace window
```

<Steps>
  <Step title="Create a thread when the order is confirmed">
    One call, at the same place in your backend where you confirm the order. `reference` is your order ID — calls with the same reference are idempotent, so retries are safe.

    ```bash theme={"dark"}
    curl -X POST https://api.open.cx/connect/threads \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "reference": "order_84421",
        "participants": [
          { "role": "customer", "external_id": "cus_991",
            "display_name": "Fatima", "language": "ar" },
          { "role": "merchant", "external_id": "mrc_204",
            "display_name": "Shawarma House", "language": "en" }
        ],
        "custom_data": { "vertical": "food", "total": 86.5, "currency": "QAR" }
      }'
    ```

    ```json theme={"dark"}
    {
      "id": "th_9f2c4e",
      "reference": "order_84421",
      "status": "open",
      "order_status": "confirmed",
      "lanes": [
        { "id": "customer_merchant", "status": "active", "supervisor_mode": "resolve" },
        { "id": "customer_courier", "status": "waiting" }
      ]
    }
    ```

    The customer↔merchant lane is live immediately. The customer↔courier lane exists but waits — there's no courier yet.

    <Tip>
      Notice `language` per participant. Fatima writes Arabic, the merchant reads English, and neither ever notices — the Supervisor translates both directions live.
    </Tip>
  </Step>

  <Step title="Add the courier when you assign one">
    ```bash theme={"dark"}
    curl -X POST https://api.open.cx/connect/threads/th_9f2c4e/participants \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "role": "courier", "external_id": "drv_318",
            "display_name": "Aleksei", "language": "en" }'
    ```

    The customer↔courier lane flips to `active`. If you reassign the order, [remove the courier](/api-reference/connect/remove-participant) and add the new one — the lane's history stays with the thread, the old courier loses access instantly.
  </Step>

  <Step title="Render the thread in your apps">
    Mint a scoped token per participant, then mount the drop-in component. The token only grants that participant's view — their lanes, their language, nothing else.

    ```bash theme={"dark"}
    curl -X POST https://api.open.cx/connect/threads/th_9f2c4e/tokens \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "participant_id": "prt_c81" }'
    ```

    ```tsx theme={"dark"}
    import { ConnectThread } from '@opencx/widget/react';

    <ConnectThread token={threadToken} />
    ```

    The component ships message list, composer, quick replies, attachment upload, read receipts, RTL layout, and the Supervisor's presence — themed by the same options as the [chat widget](/widget/configuration).

    Building your own UI? Skip the component and go headless: [send messages](/api-reference/connect/send-message) server-side and receive them via [webhooks](/connect/webhooks) or the token-scoped WebSocket.
  </Step>

  <Step title="Let order status drive the lifecycle">
    Tell Connect what the order is doing; it handles what that means for the conversation.

    ```bash theme={"dark"}
    curl -X PATCH https://api.open.cx/connect/threads/th_9f2c4e \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "order_status": "delivered" }'
    ```

    On `delivered`, participants get a wrap-up window (default 24 hours) for "the gate code didn't work"-type follow-ups, then the thread locks itself read-only. On `cancelled`, it locks immediately. Full state machine in [Threads](/connect/threads).
  </Step>

  <Step title="Tune the Supervisor — or don't">
    Every thread already has the AI Supervisor in `resolve` mode: it answers order questions from your [Actions](/actions/introduction), translates between participants, nudges a silent merchant, and escalates to your inbox when a human is needed.

    Dial it per lane if you want different behavior:

    ```bash theme={"dark"}
    curl -X PATCH https://api.open.cx/connect/threads/th_9f2c4e \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "supervisor": { "lanes": { "customer_courier": { "mode": "assist" } } } }'
    ```

    Org-wide defaults live in the dashboard under **Connect → Supervisor**. The modes — `observe`, `assist`, `resolve` — are covered in [AI Supervisor](/connect/ai-supervisor).
  </Step>
</Steps>

## That's the integration

Two API calls per order (create thread, add courier), one component per app, one PATCH per status change. Compare that to running a chat SDK: provisioning channels per pair, syncing membership, scheduling freezes and deletes, wiring moderation, and building the support handoff yourself.

<CardGroup>
  <Card title="Threads and lifecycle" icon="layer-group" href="/connect/threads">
    Lanes, roles, visibility, the order-driven state machine, retention.
  </Card>

  <Card title="AI Supervisor" icon="shield-halved" href="/connect/ai-supervisor">
    What resolve mode does, when it intervenes, and how escalation lands in your inbox.
  </Card>
</CardGroup>


# Connect threads and lanes
Source: https://docs.open.cx/connect/threads

How a Connect thread models one order: participant roles, pairwise lanes with per-role visibility, an order-driven lifecycle, identity privacy, and retention.

A **thread** is the conversation home of one order. It carries the participants, the lanes they talk in, the order's status, and your `custom_data` — and it moves through its life without your backend babysitting it.

## Roles

Every participant joins with a role: `customer`, `merchant`, or `courier`. Roles are what Connect reasons about — visibility, Supervisor behavior, and analytics are all per-role, so you never hand-manage who belongs in which channel.

Participants are identified by **your** IDs (`external_id`). Connect never exposes phone numbers or emails between participants — the thread *is* the contact channel, so a customer can reach the courier without either seeing the other's number.

## Lanes

A lane is a pairwise conversation inside the thread. Each participant sees only their own lanes; the Supervisor sees all of them.

| Lane | Customer sees | Merchant sees | Courier sees | Default |
| - | - | - | - | - |
| `customer_merchant` | ✓ | ✓ | — | On |
| `customer_courier` | ✓ | — | ✓ | On |
| `merchant_courier` | — | ✓ | ✓ | Off — enable per thread |

Why lanes instead of one open room? Because a merchant's "we're out of the grilled chicken, substitute?" belongs with the customer, while a courier's "parking is a nightmare, use the back entrance" belongs with the merchant — and neither should read the other's traffic. Lanes give you a three-touchpoint conversation with 1:1 privacy.

A lane is `waiting` until both of its roles are present (the customer↔courier lane before courier assignment), `active` while the thread is open, and `closed` when the thread locks.

## Lifecycle — the order drives it

You report order status with a single [PATCH](/api-reference/connect/update-thread); Connect translates it into conversation behavior.

```mermaid theme={"dark"}
stateDiagram-v2
  direction LR
  [*] --> open : thread created
  open --> wrap_up : order_status = delivered
  open --> locked : order_status = cancelled
  wrap_up --> locked : grace window ends (default 24h)
  locked --> archived : retention window you set ends (none by default)
  archived --> [*]
```

| You send `order_status` | Connect does |
| - | - |
| `confirmed` | Thread opens; `customer_merchant` lane active |
| `preparing`, `ready` | Status chip updates in the UI; Supervisor uses it to answer ETAs |
| `picked_up` | Courier lane messaging emphasized; merchant lane winds down |
| `delivered` | Wrap-up window starts; when it ends, thread locks read-only |
| `cancelled` | Thread locks immediately; Supervisor handles "why was it cancelled?" |

Locked threads stay readable to participants and your team but accept no new messages — participants who need more help get one tap into your regular support flow via the Supervisor. Archived threads leave the apps entirely and remain queryable by [API](/api-reference/connect/list-threads). Connect never deletes thread history on a timer — it is removed when you request deletion or your account is terminated. See [Data retention](/security/data-retention).

Grace and retention windows are configurable per org in **Connect → Lifecycle**, and per thread at [creation](/api-reference/connect/create-thread). The grace window defaults to 24 hours. No retention window is set by default, so a locked thread stays locked until you set one.

## Reassignment

Couriers change; threads shouldn't. [Remove](/api-reference/connect/remove-participant) the old courier and [add](/api-reference/connect/add-participant) the new one:

* The removed courier loses access immediately — including history.
* The new courier joins the same lane with fresh context; the Supervisor briefs them with a one-line summary ("Customer asked to leave the order at the gate, code 4411").
* The customer keeps one continuous conversation instead of starting over.

## What the thread carries

* **`reference`** — your order ID. Unique per org, idempotency key for creation, and the join key for everything analytics.
* **`custom_data`** — arbitrary JSON (vertical, basket value, promo flags). Surfaced to the Supervisor as answering context and returned on every read.
* **Messages** — text and attachments, each stamped with lane, sender participant, and per-language `translations`.
* **Events** — join/leave, status changes, Supervisor interventions: the full audit trail of the order conversation, exportable via [API](/api-reference/connect/list-messages) and streamed via [webhooks](/connect/webhooks).

## Privacy defaults

* No participant ever sees another's contact details — identity is display name + role, full stop.
* The Supervisor masks phone numbers, emails, and payment details typed into any lane (see [AI Supervisor](/connect/ai-supervisor)); attempts to move the conversation off-platform are flagged to you by webhook.
* Locked-thread history is kept for disputes until you request deletion or your account is terminated — never removed because it reached a certain age.

<CardGroup>
  <Card title="AI Supervisor" icon="shield-halved" href="/connect/ai-supervisor">
    The fourth participant: observe, assist, and resolve modes per lane.
  </Card>

  <Card title="Create a thread" icon="code" href="/api-reference/connect/create-thread">
    Full request/response reference for thread creation.
  </Card>
</CardGroup>


# Connect webhooks and events
Source: https://docs.open.cx/connect/webhooks

Every Connect event streamed to your backend — thread lifecycle, messages with translations, participant changes, Supervisor interventions and escalations.

Connect emits webhooks for everything that happens in a thread, so your backend can mirror messages into your own systems, trigger ops flows on escalations, and audit Supervisor activity. Configure endpoints in **Settings → Webhooks** — Connect events share the delivery pipeline, retry policy, and `svix-signature` HMAC verification used by [all OpenCX webhooks](/api-reference/webhooks/types).

## Events

| Event | Fires when |
| - | - |
| `connect.thread.created` | A thread is created |
| `connect.thread.status_changed` | `open → wrap_up → locked → archived`, or `order_status` changes |
| `connect.participant.added` | A participant joins (e.g. courier assigned) |
| `connect.participant.removed` | A participant is removed (e.g. courier reassigned) |
| `connect.message.created` | Any participant or the Supervisor sends a message |
| `connect.supervisor.intervened` | The Supervisor acts: answer, nudge, safety mask |
| `connect.supervisor.escalated` | A thread escalates into a support session |

## Payloads

All events share the standard envelope: `event`, `organization_id`, `data`, and an ISO `timestamp`.

`connect.message.created`

```typescript theme={"dark"}
{
  event: 'connect.message.created';
  organization_id: string;
  data: {
    thread_id: string;
    reference: string;              // your order ID
    lane: 'customer_merchant' | 'customer_courier' | 'merchant_courier';
    message: {
      id: string;
      sender: { participant_id: string; role: 'customer' | 'merchant' | 'courier' | 'supervisor' };
      text: string;                 // original text (post safety-masking)
      translations: Record<string, string>;   // e.g. { ar: '...', en: '...' }
      attachments: { url: string; content_type: string }[];
      created_at: string;
    };
  };
}
```

`connect.supervisor.intervened`

```typescript theme={"dark"}
{
  event: 'connect.supervisor.intervened';
  organization_id: string;
  data: {
    thread_id: string;
    reference: string;
    lane: string;
    kind: 'answer' | 'nudge' | 'safety_mask' | 'off_platform_flag';
    detail: string;                 // human-readable description
    message_id?: string;            // present when the intervention produced a message
    timestamp: string;
  };
}
```

`connect.supervisor.escalated`

```typescript theme={"dark"}
{
  event: 'connect.supervisor.escalated';
  organization_id: string;
  data: {
    thread_id: string;
    reference: string;
    session_id: string;             // the OpenCX session opened in your inbox
    reason: 'sentiment' | 'unanswered' | 'requested_human' | 'prohibited_topic' | 'safety';
    summary: string;                // the context handed to your team
    timestamp: string;
  };
}
```

`connect.thread.status_changed`

```typescript theme={"dark"}
{
  event: 'connect.thread.status_changed';
  organization_id: string;
  data: {
    thread_id: string;
    reference: string;
    status: 'open' | 'wrap_up' | 'locked' | 'archived';
    order_status: string;
    timestamp: string;
  };
}
```

<Tip>
  Going headless (your own chat UI)? Subscribe to `connect.message.created` and render from the `translations` map for each viewer's language — the same data the drop-in component uses.
</Tip>

<CardGroup>
  <Card title="Webhook event types" icon="globe" href="/api-reference/webhooks/types">
    Signature verification, retries, and the platform-wide event catalog.
  </Card>

  <Card title="Connect API reference" icon="code" href="/api-reference/connect/index">
    The REST surface these events mirror.
  </Card>
</CardGroup>


# Manage Contacts
Source: https://docs.open.cx/contacts/manage-contacts

Learn how to manage your contacts and enrich them with our +200 million users database

<Frame>
  <img alt="Contacts page in the OpenCX dashboard" />
</Frame>

## Terminology

<CardGroup>
  <Card title="What is a contact?" icon="user" href="#what-is-a-contact" />
</CardGroup>

## Create a contact

<CardGroup>
  <Card title="Using the API" icon="code" href="#1-using-the-api" />

  <Card title="Using the widget" icon="code" href="/widget/introduction" />

  <Card title="From emails" icon="inbox" href="#3-from-emails" />

  <Card title="From phone calls" icon="phone" href="#4-from-phone-calls" />
</CardGroup>

## Advanced Topics

<CardGroup>
  <Card title="Attach custom data to a contact" icon="code" href="#adding-custom-data-to-a-contact" />
</CardGroup>

***

### What is a contact?

A contact is a user that can interact with the chatbot, phone AI, or email AI. A single contact might have multiple conversations across different channels.

***

### How do I create a contact?

You can create a contact in your organization in two ways:

#### 1. Using the API

We have a simple public API that allows you to manage contacts in your organization. You can use the API to [create a contact](/api-reference/contacts/create) or to [authenticate a contact](/api-reference/widget/authenticate-contact).

#### 2. Using the widget

Whenever you embed the copilot widget in your application, you can use the widget options to create a contact. Read more about this option in the [widget documentation](/widget/introduction).

#### 3. From emails

When you send emails using our APIs, OpenCopilot will automatically create a contact for you (if it doesn't exist yet) and assign it to the conversation.

#### 4. From phone calls

When you receive (or initiate) a phone call using our APIs, OpenCopilot will automatically create a contact for you (if it doesn't exist yet) and assign it to the conversation.

***

### Adding custom data to a contact

We support attaching a phone number, email, or name to a contact. However, you can also add any custom data you want to associate with the contact. This data will be returned in the response and can be used for any purpose you want. Just make sure it's a valid JSON string object. The custom data is a simple JSON object. You can add any key-value pairs you want to it, for example:

```jsx theme={"dark"}
const widgetOptions = {
  token: "your_copilot_token_goes_here",
  user: {
    data: {
      name: "your_user_name",
      email: "your_user_email",
      customData: {
        // any custom data you want to send to the copilot backend
        avatar: "your_user_avatar_url",
        phone: "your_user_phone",
        key1: "value1",
        balance: 100,
        age: 25,
      }
    }
  },
```

You can use the API or the widget to add custom data to a contact.


# Core Concepts
Source: https://docs.open.cx/core-concepts

The OpenCX vocabulary — session, ticket, contact, autopilot, handoff, action, training scenario, insight, channel — defined in one place.

These terms show up across every page in these docs and in your OpenCX dashboard. Bookmark this page.

## Conversation

<AccordionGroup>
  <Accordion title="Session" icon="comments">
    A single conversation with a customer, on any channel. A session starts when the first message arrives and ends when the session is resolved or closed. Every message, handoff event, and action call is attached to a session.
  </Accordion>

  <Accordion title="Ticket" icon="ticket">
    A session's human-readable ID (e.g. `#4521`). When a session hands off to a helpdesk like Zendesk or Hubspot, the ticket number carries over so your team can reference the same conversation everywhere.
  </Accordion>

  <Accordion title="Contact" icon="address-card">
    The customer on the other side of a session. Identified by email, phone number, or a custom ID. Contacts persist across sessions — one contact can have many sessions over time.
  </Accordion>

  <Accordion title="Channel" icon="satellite-dish">
    Where a message came from: `web` (chat widget), `phone`, `email`, `whatsapp`, `sms`, `slack`, `api`. Every session has one channel.
  </Accordion>
</AccordionGroup>

## AI behavior

<AccordionGroup>
  <Accordion title="Autopilot" icon="sliders">
    Per-channel switch that controls whether the AI replies automatically. Off = every message routes to your team's inbox. On = AI handles what it can, hands off the rest. You can also gate autopilot by **topic** (reply to billing, skip login).
  </Accordion>

  <Accordion title="Handoff" icon="user-group">
    The event where the AI stops responding and a human agent takes over. Triggered by low confidence, prohibited topics, frustrated language, or an explicit customer request. Every handoff records a reason and the full conversation history.
  </Accordion>

  <Accordion title="Training Scenario" icon="book-open">
    A specific instruction you write by hand — either a **behavioral** rule (always active, controls tone/style) or a **scenario-specific** answer (triggered when a matching question comes in). See [Training scenarios](/ai-instructions/training-scenarios).
  </Accordion>

  <Accordion title="Action" icon="bolt">
    A real API call the AI can make during a conversation — look up an order, cancel a subscription, create a ticket. Defined with an OpenAPI-style spec. See [AI Actions](/actions/introduction).
  </Accordion>

  <Accordion title="Workflow" icon="diagram-project">
    A multi-step automation triggered by an event (handoff, schedule, webhook). Workflows can call AI questions, send messages, update tickets, or run JavaScript. Configured per-org from the dashboard.
  </Accordion>
</AccordionGroup>

## Content and analytics

<AccordionGroup>
  <Accordion title="Help Center" icon="compass">
    A self-service portal you author inside OpenCX. Articles are grouped into topics; translations are built in. The AI reads from your help center as one of its knowledge sources.
  </Accordion>

  <Accordion title="Knowledge Source" icon="database">
    A connected external system the AI reads from — Zendesk articles, Notion, Google Drive, Confluence, Dropbox, or a crawled website. Lives alongside your help center.
  </Accordion>

  <Accordion title="Insight" icon="lightbulb">
    An automatically extracted theme from recent sessions — a recurring complaint, a feature request, a broken flow. Used to prioritize content updates and product fixes.
  </Accordion>

  <Accordion title="CSAT" icon="star">
    Customer satisfaction score. Collected after a session resolves; feeds into analytics and per-agent reporting.
  </Accordion>

  <Accordion title="Insight category" icon="tag">
    A label applied to insights to group recurring themes (billing, login, feature request). The AI auto-suggests categories; you confirm or override.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="How OpenCX Works" icon="diagram-project" href="/how-opencx-works">
    See how the concepts fit together in a single flow.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Put the concepts into practice — live agent in 10 minutes.
  </Card>

  <Card title="AI Safety" icon="shield" href="/safety/introduction">
    The boundaries: inspect mode, PII redaction, prohibited topics.
  </Card>

  <Card title="Agent Training" icon="book" href="/knowledge/introduction">
    Deep dive on what the AI reads from and how to train it.
  </Card>
</CardGroup>


# CRM Integrations
Source: https://docs.open.cx/crms/introduction

When your AI agent hands off a conversation to a human agent, Open.cx automatically displays comprehensive customer information from your CRM system directly in your support inbox.

When your AI agent hands off a conversation to a human agent, Open.cx automatically displays comprehensive customer information from your CRM system directly in your support inbox.

This gives your human agents complete context to provide exceptional, personalized support without asking customers to repeat information.

## Supported CRM Systems

<CardGroup>
  <Card title="HubSpot" icon="hubspot" href="/integrations/hubspot/overview">
    Connect with HubSpot to access contacts, companies, deals, and ticket history
  </Card>

  <Card title="Salesforce" icon="salesforce" href="/crms/salesforce">
    Connect with Salesforce to access contacts, accounts, opportunities, and case history
  </Card>
</CardGroup>

## How CRM Integration Works

1. **Connect Your CRM**: Authenticate your CRM system with Open.cx using OAuth or API keys
2. **AI Handles Initial Support**: Your AI agent manages the conversation as usual
3. **AI Handoff Triggered**: When AI escalates to human agent, CRM data is automatically retrieved
4. **Context Display**: Human agent sees complete customer information in their inbox
5. **Informed Support**: Human agent provides personalized support based on complete customer history

## Getting Started

Choose your CRM system below to get started with the integration:

<CardGroup>
  <Card title="Set up HubSpot Integration" icon="hubspot" href="/integrations/hubspot/overview">
    Complete guide to connecting HubSpot with Open.cx for human agent context
  </Card>

  <Card title="Set up Salesforce Integration" icon="salesforce" href="/crms/salesforce">
    Complete guide to connecting Salesforce with Open.cx for human agent context
  </Card>
</CardGroup>

## Need Help?

If you need assistance with CRM integrations or have questions about supported features, please contact our support team or check out our API documentation.


# Customizing the Copilot
Source: https://docs.open.cx/dashboard/custom_state

1. Access the Directory: Users should navigate to the directory where the integration functions need to be stored. In this case, the directory path is: llm-server/integrations/trello.py 2. Create a…

### To integrate a third-party application (e.g., Trello) with the OpenCopilot's LLM server, users should create functions similar to the provided `process_state` function and store them in the specified directory. Here's a step-by-step guide on what users need to do:

1. **Access the Directory**: Users should navigate to the directory where the integration functions need to be stored. In this case, the directory path is: `llm-server/integrations/trello.py`
2. **Create a Python File**: Users should create a new Python file with a meaningful name that reflects the integration they are building. For example, if integrating with Trello, they can name it `trello.py`. This file will contain the integration functions.
3. **Write Integration Functions**: Inside the `trello.py` file, users should define functions similar to the `process_state` function provided in the example. These functions should perform the following tasks:

   * **Retrieve Data**: Access the third-party API for relevant information.
   * **Data Transformation**: Remove any properties from the API response that are not relevant to the entity or that are not needed to make future API calls. You can see an example of how to do this in the process\_state function in the Trello integration file: [https://github.com/openchatai/OpenCopilot/blob/6c266686d73371fb50961eeec8e85452e633ef91/llm-server/integrations/trello.py](https://github.com/openchatai/OpenCopilot/blob/6c266686d73371fb50961eeec8e85452e633ef91/llm-server/integrations/trello.py). In other words, the API response may contain more information than you need. For example, if you are only interested in the name and description of a Trello card, you can remove any other properties from the API response. This will make the API response smaller and easier to process..

**When writing functions for the LLM server, please follow these guidelines:**

* Structure and format the data returned by functions in a consistent way. The output of process\_state should be compact, since there are size limitations on context. We plan to add features to automatically control context size, but for now try to keep it minimal through manual transformations.
* By writing tidy, documented functions that return clean data, you will make it easier for the AI to understand and stay in context. This helps it provide useful responses to users. For example, an integration function for Trello could retrieve data about Trello cards or members and transform it as required.

4. **Save the File**: Once the integration functions are defined, users should save the `trello.py` file in the specified directory.
5. **Usage in LLM Server**: Usage is straightforward. You can invoke the integration functions within the LLM server by specifying the integration file's name when making calls to the server, just add another argument app: trello. The server will automatically detect and run the necessary functions, loading the data into memory. It will also periodically refresh the data to ensure it remains up-to-date and relevant.

## Example

```python theme={"dark"}
def process_state(state):
    """Processes the current state of the Copilot.
    Args:
        state: The current state of the Copilot.
    Returns:
        A dictionary containing the processed state.
    """

    # Retrieve data from Trello
    trello_client = TrelloClient()
    boards = trello_client.get_boards()

    # Transform the data to match the LLM server's requirements
    processed_boards = []
    for board in boards:
        processed_boards.append({
            "id": board.id,
            "name": board.name,
            "lists": board.lists,
        })

    # Return the processed state
    return {
        "boards": processed_boards,
    }

This is just a simple example, but it should give you an idea of how to write integration functions for the LLM server. You can use the same principles to integrate with any
```


# Integrations
Source: https://docs.open.cx/dashboard/introduction

Connect your helpdesks, CRMs, e-commerce platforms, and automation tools from the integrations settings.

Connect your helpdesks, CRMs, e-commerce platforms, and automation tools from the [integrations settings](https://platform.open.cx/settings/integrations). Conversations, handoffs, and customer data stay in sync across systems.

<Tip>
  Pick the integration you want to connect below and follow its setup guide.
</Tip>

<Tabs>
  <Tab title="Ticketing & CRMs">
    <CardGroup>
      <Card title="Zendesk" icon="headset" href="/dashboard/zendesk_integration">
        Ticket creation and handoff through Sunshine Conversations or the Zendesk API.
      </Card>

      <Card title="HubSpot" icon="users-viewfinder" href="/integrations/hubspot/overview">
        Unified ticketing and live chat handoff in HubSpot.
      </Card>

      <Card title="Intercom" icon="message" href="/integrations/intercom/overview">
        Conversation sync and handoff into your Intercom inbox.
      </Card>

      <Card title="Gorgias" icon="cart-shopping" href="/integrations/gorgias/overview">
        AI replies and ticket handoff into your Gorgias helpdesk.
      </Card>

      <Card title="Salesforce" icon="cloud" href="/integrations/salesforce/overview">
        Case management and chat handoff in Salesforce.
      </Card>

      <Card title="Creatio" icon="grid-2" href="/integrations/creatio/overview">
        Case creation and workflow automation in Creatio.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="E-commerce & Automation">
    <CardGroup>
      <Card title="Shopify" icon="bag-shopping" href="/integrations/shopify/overview">
        Order lookup, product search, and customer metadata enrichment.
      </Card>

      <Card title="FareHarbor" icon="anchor" href="/integrations/fareharbor/overview">
        Tour and activity booking, availability checks, and payment links.
      </Card>

      <Card title="Jira" icon="list-check" href="/integrations/jira/overview">
        Turn customer conversations and AI recommendations into Jira issues.
      </Card>

      <Card title="Zapier" icon="bolt" href="/dashboard/zapier">
        Trigger zaps and run actions from OpenCX events.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## How Integrations Work

<AccordionGroup>
  <Accordion title="Connect from the dashboard" icon="plug">
    Each integration is configured in **Settings > Integrations**. Select the integration, follow the connection steps, and OpenCX handles the rest.
  </Accordion>

  <Accordion title="Two-way sync" icon="arrows-rotate">
    Conversations and customer data flow between OpenCX and the connected platform. When the AI hands off, your agents see full context in their existing tool.
  </Accordion>

  <Accordion title="Per-integration configuration" icon="sliders">
    Each integration has its own settings for handoff behavior, field mapping, and sync preferences. See the individual setup guides for details.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Build Agents" icon="robot" href="/build-agents/get-started">
    Configure your AI agent's knowledge and behavior.
  </Card>

  <Card title="Agent Training" icon="book" href="/knowledge/introduction">
    Connect knowledge sources like Zendesk articles, Notion, and more.
  </Card>

  <Card title="Autopilot & Topics" icon="sliders" href="/handoff/topics">
    Control which conversations the AI handles per channel.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    AI-to-human escalation across all channels.
  </Card>
</CardGroup>


# Thanks for having the demo with us
Source: https://docs.open.cx/dashboard/onboarding/intro

Welcome to Open.cx! We're excited to help you get started. Follow these simple steps to kick off your onboarding process.

<Steps>
  <Step title="Join Our Slack Support Channel">
    Get direct access to the entire Open.cx team through our Slack support channel, where you'll have:

    * **Real-time support** from our team
    * A place to ask questions or share feedback anytime

    *We'll send you an invitation to join shortly.*
  </Step>

  <Step title="Resources We Need From You">
    To ensure a smooth onboarding process, we'll need:

    * **One technical person** (engineer) for **no more than 2 hours per week** to help with:
      * Technical setup
      * API configurations
    * **One project owner** (PM, Operations, or CS Manager) to:
      * Manage the integration from your side
      * Make decisions about configurations
      * Be the main point of contact

    This helps us ensure a successful and efficient implementation.
  </Step>

  <Step title="Start Your 14-Day Trial Period">
    Once you're ready, we'll activate your **14-day trial period**. During this time, we'll need your help with:

    **A. Sync Your Knowledge Base**

    * Provide access to your knowledge base sources
    * Our AI will train on this data
    * **Time required:** Less than 1 hour to complete the sync
    * We offer **25+ one-click integrations** to connect with your knowledge base seamlessly. [Learn more here](/knowledge/introduction)

    **B. Backend/API Actions**

    * Provide any backend/API actions your team wants to integrate with Open.cx
    * We will assign an **engineer from our team** to fully assist in onboarding and configuring any API actions
    * **Time required:** Less than 1 hour to complete the sync

    **C. Enable One Communication Channel**

    * Activate one channel (e.g., email, web, or phone)
    * Start testing and interacting with the AI to see how it works
  </Step>

  <Step title="Review Your Results">
    Most of our users achieve **over 50% automation of their entire support operations within the
    first month** of going live. During your trial, we'll help you lay the groundwork to maximize
    automation and efficiency right from the start.
  </Step>

  <Step title="Complete Your Trial">
    At the end of the 14-day trial period, you'll be expected to make a decision about moving forward
    with Open.cx. We'll provide a full recap of: - How the system performed - Key metrics and ROI from
    your trial
  </Step>

  <Step title="Pricing">
    Our simple and transparent pricing model:

    * **Base fee:** \$250 USD per month
      * Includes unlimited support agents
    * **AI Resolution fee:** \$0.30 per successful AI resolution

    [View detailed pricing information →](/dashboard/onboarding/pricing)
  </Step>
</Steps>

***

Need help or have questions?\
Feel free to reach out on Slack—we're here for you every step of the way!


# Pricing
Source: https://docs.open.cx/dashboard/onboarding/pricing

Simple, transparent pricing based on the value we deliver — base subscription plus usage-based resolution pricing, with comparison against other providers.

## Pricing Principles

<AccordionGroup>
  <Accordion title="Simple and transparent">
    We believe in straightforward pricing. One base fee, and you only pay for successful AI
    resolutions.
  </Accordion>

  <Accordion title="Full access to all features">
    No feature restrictions or hidden paywalls. Every subscription includes access to all current
    and future features.
  </Accordion>

  <Accordion title="Pay for value">
    You only pay when our AI successfully resolves support tickets - if we don't deliver value, you
    don't pay.
  </Accordion>

  <Accordion title="Unlimited human agents">
    No per-seat pricing. Add as many support agents as you need without additional costs.
  </Accordion>
</AccordionGroup>

## Our Pricing Model

### Base Subscription

* **\$250 USD per month**
* Includes:
  * Unlimited human agents
  * Full access to all features
  * AI-powered workspace
  * All communication channels
  * Analytics and reporting

### Usage-Based Pricing

You only pay when our AI successfully resolves a support ticket:

* **\$0.30 per successful AI resolution**

## How We Define Resolutions

### Successful Resolution Criteria

A ticket is considered successfully resolved when either:

1. The customer explicitly confirms their issue is resolved
2. The conversation naturally concludes with no further questions for 24 hours

### Resolution Examples

<AccordionGroup>
  <Accordion title="Example 1: Direct Confirmation">
    * AI: "Is your issue resolved?" - Customer: "Yes, thank you!" - Result: Marked as resolved,
      \$0.30 charged
  </Accordion>

  <Accordion title="Example 2: Natural Conclusion">
    * AI provides solution - Customer doesn't respond further - After 24 hours: Marked as resolved,
      \$0.30 charged
  </Accordion>

  <Accordion title="Example 3: Handoff to Human">
    * AI cannot fully resolve issue - Conversation handed to human agent - Result: No charge for AI
      resolution
  </Accordion>
</AccordionGroup>

## Comparison with Other Providers

Our pricing offers significant savings compared to traditional support platforms:

| Agents | Monthly Tickets | Zendesk | Intercom | Open.cx |
| - | - | - | - | - |
| 30 | 2,000 | \$7,800 | \$6,400 | \$850\* |

\*Open.cx cost breakdown:

* \$250 base fee
* \~\$600 for AI resolutions (assuming 50% AI resolution rate)
* **Total savings: Over 85% compared to traditional platforms**

## Why Choose Open.cx?

1. **Cost Effective**: Pay significantly less than traditional support platforms
2. **Scalable**: Add unlimited agents without additional costs
3. **Efficient**: AI automation reduces human agent workload by \~50%
4. **Risk-Free**: Only pay for successful resolutions
5. **Full Featured**: Access to all features without restrictions

***

Need more information? [Contact our sales team](mailto:sales@open.cx) or start your 14-day trial today.


# Dashboard overview
Source: https://docs.open.cx/dashboard/overview

Landing tour of the OpenCX dashboard — where agents, inbox, knowledge, analytics, and organisation settings live, and how the top-level navigation is wired up.



# Zapier
Source: https://docs.open.cx/dashboard/zapier

Open is integrated with Zapier! You can automate multiple Open actions and triggers using zapier.com and using OpenCX app.

This guide shows you how to create your own zaps using Open's Action and Triggers.

A Zapier zap consists of a Trigger and an Action.

Zapier Triggers allows you to do an action when something happens.

Zapier Action is an action that happens when a trigger is activated.

## Open Actions

<CardGroup>
  <Card title="Create a contact" icon="user-plus">
    Create a new contact to be stored in your Open Dashboard.
  </Card>

  <Card title="Delete a contact" icon="user-minus">
    Deletes a contact from your contact list.
  </Card>

  <Card title="List contacts" icon="user-group">
    Lists all your contacts.
  </Card>

  <Card title="Create Chat Session" icon="message-plus">
    Creates a chat session with a contact in any type of channel
  </Card>

  <Card title="List Chat Sessions" icon="messages">
    Lists all chat sessions of organization.
  </Card>

  <Card title="List Chat Session History" icon="messages">
    Lists the history of a particular chat session
  </Card>

  <Card title="Make AI Phone Call" icon="phone">
    Make an AI phone call using your phone number created in Open
  </Card>

  <Card title="Send Emails" icon="envelope">
    Send emails to multiple contacts, possibly with a time delay. To send emails using the API, you
    must first verify the domain you want to send emails from. You can add and verify custom domains
    in the settings.
  </Card>
</CardGroup>

## Open Triggers

<CardGroup>
  <Card title="Conversation Started" icon="messages">
    Is triggered when a new conversation of any channel type starts
  </Card>

  <Card title="Conversation Ended" icon="messages">
    Is triggered when a new conversation of any channel type ends
  </Card>

  <Card title="Handoff to Human Agent" icon="user-headset">
    Triggers when a conversation is handed off to a human agent. Note that a handoff event can
    happen for multiple reasons; for example, a human agent might decide to take over the
    conversation, or the AI might decide to hand off the conversation to a human agent.
  </Card>
</CardGroup>

## Steps for creating you first Zap using Open's Actions and Triggers

### Creating a Zap using one of Open's Triggers

<Steps>
  <Step title="Go to your Zapier Zaps dashboard">
    <Frame>
      <img alt="Zapier Zaps dashboard landing view" />
    </Frame>

    Firstly go to your Zapier Zaps Dashboard using [this](https://zapier.com/app/zaps) link, and signup if you do not have an account.
  </Step>

  <Step title="Create a new Zap">
    Click on the "+ Create" button on the top right to create a new Zap. The following screen should now be visible.

    <Frame>
      <img alt="New Zap editor with empty Trigger and Action blocks" />
    </Frame>

    Press on the box with the title "Trigger"
  </Step>

  <Step title="Choose OpenCX as the trigger app">
    This screen should now be visible.

    <Frame>
      <img alt="Zapier trigger app search panel" />
    </Frame>

    In the search bar type "OpenCX" and our app should be visible to choose.

    <Frame>
      <img alt="OpenCX app result selected in the Zapier app picker" />
    </Frame>

    Choose this app.
  </Step>

  <Step title="Pick a trigger event and connect your account">
    This screen should now be visible.

    <Frame>
      <img alt="List of OpenCX trigger events in Zapier" />
    </Frame>

    After choosing one of our triggers for this example we chose "Conversation Started", you will then press on the sign in button below to sign in using you Open Account so we can verify your identity.
    You will then be redirected to this page

    <Frame>
      <img alt="Zapier prompt asking for an OpenCX API key" />
    </Frame>

    Here we request an API key that is connected to your OpenCX account. To get this API key, go to your OpenCX dashboard and open Settings.

    <Frame>
      <img alt="OpenCX dashboard settings menu" />
    </Frame>

    Then choose "API Token" from the left menu

    <Frame>
      <img alt="API Tokens page in OpenCX settings" />
    </Frame>

    Press "Add" to add a new token, choose a name for this token. Copy the generated token and store it in a safe place, then paste it in the Zapier Login Screen like so.

    <Frame>
      <img alt="Zapier login screen with the OpenCX API key pasted" />
    </Frame>

    Then press continue and you will be immediatly redirected to your Zap.

    Your trigger part of the Zap is now setup and ready!
  </Step>
</Steps>

### Creating a Zap using one of Open's Actions

For actions you will do the exact same steps as Triggers with the exception that you will be choosing Action instead.


# Connect Email
Source: https://docs.open.cx/email/forwarding

Go live with AI email — verify your domain, register your support address, configure forwarding at your mail host, and pass the connection test.

You do not need a self-hosted mail server; set this up in your [OpenCX dashboard](https://platform.open.cx).

## Prerequisites

<Warning>
  Each registered address is **globally unique**. If this address is already in use, you cannot add it.
</Warning>

* <Tooltip>**Verified domain**</Tooltip> in your [OpenCX dashboard](https://platform.open.cx/settings/domains). See [Sending Domains & DNS](/email/sending-domains) for the exact records and why a dedicated subdomain is recommended.

## What You Will Configure

1. **Public support address** — the inbox customers use; register it exactly in the dashboard.
2. **Forward at your host** — copy (or all) mail to <Tooltip>**`forwarding@opencopilot.so`**</Tooltip>.

<Tip>
  Forward **all** mail for that address when possible; filters that drop automated mail can break the <Tooltip>connection test</Tooltip>.
</Tip>

## Go Live

<Steps>
  <Step title="Verify Your Domain">
    Confirm ownership of your domain under **[Settings → Domains](https://platform.open.cx/settings/domains)** by adding the DNS records shown there — see [Sending Domains & DNS](/email/sending-domains). This allows you to send emails from addresses on that domain.
  </Step>

  <Step title="Register Your Support Address">
    Go to **[Channels → AI Email](https://platform.open.cx/channels/configure/mail)** and add the address your customers write to (e.g. `support@yourcompany.com`).
  </Step>

  <Step title="Set Up Forwarding In Your Email Provider">
    Tell your email provider to forward a copy of incoming mail to **`forwarding@opencopilot.so`**.

    <Tabs>
      <Tab title="Gmail">
        **[Settings → See all settings](https://mail.google.com/mail/u/0/#settings/general) → [Forwarding and POP/IMAP](https://mail.google.com/mail/u/0/#settings/fwdandpop) → Add a forwarding address** → enter `forwarding@opencopilot.so` → confirm the verification email → choose **Forward a copy**.
      </Tab>

      <Tab title="Outlook / Microsoft 365">
        **[Settings → Mail → Forwarding](https://outlook.live.com/mail/0/options/mail/forwarding)** → enter `forwarding@opencopilot.so` and save. For Microsoft 365 admin-managed forwarding, see the [Exchange admin center](https://admin.exchange.microsoft.com/#/mailflow/rules).
      </Tab>

      <Tab title="Other Providers">
        Look for a **Forwarding** or **Mail rules** setting → add `forwarding@opencopilot.so` as the destination → save.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Run The Connection Test">
    Status becomes **Connected** once a test email to your address comes back through your forwarding rule. If it does not, check the rule at your provider and run the test again.
  </Step>
</Steps>

<Tip>
  Web forms and help center tickets that forward to your support address are handled the same way — no separate configuration needed.
</Tip>

## Copy Replies To Your CRM

Customers' emails already reach your CRM when it syncs the forwarded mailbox. Replies sent from OpenCX do not pass through that mailbox, so the CRM never sees your side of the thread.

Most CRMs offer a dedicated address: anything copied to it is attached to the matching contact's timeline. Add that address under **[Channels → AI Email](https://platform.open.cx/channels/configure/mail) → your inbox → Copy replies to**. Every reply sent from that inbox — AI, automated and human — is then quietly copied to it. Customers never see the copy.

<Note>
  * Only replies OpenCX sends itself are copied. Replies delivered through a connected ticketing system follow that system's own rules.
  * Some CRMs only accept copies whose sender is a registered user. If replies do not appear, add your inbox address to the CRM user who owns it.
</Note>

## Expected Results

| Item | Detail |
| - | - |
| **Forwarding inbox** | Mail must reach the shared address; allow up to about **one minute** before it shows in the dashboard (**best effort**). |
| **Connection test** | May take up to **5 minutes**. Retry if it shows failed. If it fails again, see [Troubleshooting](/email/troubleshooting). |

<Note>
  After mail reaches `forwarding@opencopilot.so`, allow a short delay before it shows in the dashboard.
</Note>

## Related Documentation

<CardGroup>
  <Card title="Troubleshooting" icon="wrench" href="/email/troubleshooting">
    Connection failures, missing replies, and common fixes.
  </Card>

  <Card title="Email Flow" icon="diagram-project" href="/email/forwarding-rules">
    Session matching, threading, and outbound format.
  </Card>

  <Card title="Autopilot And Topics" icon="sliders" href="/handoff/topics">
    Channel-level Autopilot and topic rules.
  </Card>

  <Card title="Email API" icon="code" href="/api-reference/email/email_api">
    Domains, verification, and transactional sends.
  </Card>
</CardGroup>


# Email Flow
Source: https://docs.open.cx/email/forwarding-rules

How forwarded mail is matched to sessions — session tokens, new-thread vs reply logic, and outbound formatting.

Use **[Connect Email](/email/forwarding)** first if you are still setting up your address and provider rules. For diagnosing issues, see **[Troubleshooting](/email/troubleshooting)**.

<Tip>
  **Email Flow** explains how **OpenCX** matches and processes mail after go-live. Setup steps stay on [Connect Email](/email/forwarding).
</Tip>

## Path Of A Message

```mermaid theme={"dark"}
flowchart LR
  A([Customer]) --> B[Support inbox]
  B --> C[Forward rule]
  C --> D[Forwarding inbox]
  D --> E[Match To and session]
  E --> F[Send reply]
  F --> G([Customer])

  style A fill:#1a5c20,color:#fff,stroke:#267a2e
  style G fill:#1a5c20,color:#fff,stroke:#267a2e
```

<Steps>
  <Step title="Customer Sends Email">
    A customer emails your support address (e.g. `support@yourcompany.com`).
  </Step>

  <Step title="Forwarded To OpenCX">
    Your email provider automatically forwards a copy to **OpenCX**.
  </Step>

  <Step title="Matched To A Conversation">
    **OpenCX** recognizes your registered address and either continues an existing conversation or starts a new one.
  </Step>

  <Step title="AI Generates Reply">
    When <Tooltip href="https://platform.open.cx/settings/autopilot">**Autopilot**</Tooltip> is enabled, the AI drafts an HTML-formatted reply using your knowledge base and tools, and sends it from your registered address with your signature. When Autopilot is off or the conversation is escalated, your team replies from the [inbox](https://platform.open.cx/inbox) instead.
  </Step>
</Steps>

<Note>
  Treat the thread in your [OpenCX dashboard](https://platform.open.cx) as the **authoritative** copy. Mail clients may or may not collapse replies into one visual thread depending on the mail client.
</Note>

## New Thread Vs Reply

OpenCX first checks the email's reply headers and the session references in its quoted body. Replies from the original customer or an existing email participant continue the session normally.

When a reply header or an embedded session ID identifies an existing email session, a reply from someone outside its participant list is saved as an **internal note on that session**. The note is attributed to **AI**, identifies the sender, explains why it is private, and quotes the email. Attachments are kept with the note, and your organization's data redaction settings apply to its text. The sender and any recipients on that private email are not added to the session's participants or automatically included in outgoing replies. The AI does not reply to the note or use its content to answer the customer.

A human reply saved this way reopens a closed session without changing its assignee. Automatic responses are saved privately without reopening. If the session has a linked Zendesk ticket, OpenCX also copies the reply there as a private note. Zendesk tickets that are permanently closed cannot accept new notes.

A visible `REF #12345` also works when email formatting places the number inside a link. A number alone still requires the sender to be the original customer or an existing participant.

If those checks cannot identify a session, OpenCX can join two separate customer replies to the **same original email**, even when that original email never reached OpenCX. This fallback requires:

* The same customer and receiving inbox within your organization.
* The same subject after removing leading `Re:` prefixes.
* Exactly one matching session with a customer reply received within the previous seven days.

Automatic responses and messages treated as spam do not use this fallback. Missing reply information or multiple possible sessions leave the email unmatched, so normal new-session rules apply. Matching by subject alone is never enough.

The shared-parent fallback applies to emails received after this update; older messages are not retroactively linked. Existing reply-header and session-reference matches keep priority.

## Outbound Format

Replies keep the original subject with a **Re:** prefix. A small reference number is included automatically for tracking. All outgoing emails are formatted as **HTML** with unsafe content removed before delivery.

When forwarding a session from the inbox, your note and email signature appear above the forwarded history. Custom email templates place that history at `{{quoted_content}}`; keep this placeholder below your signature. Without that placeholder, the history follows the template. The `{{agent_name}}` placeholder uses the forwarding agent's customer-facing name, even when the new session is assigned to someone else.

## Good To Know

<AccordionGroup>
  <Accordion title="Multiple Addresses On One Org" icon="envelopes">
    AI replies send from the address the customer wrote to. Routing keys off **To**, so each registered address is matched independently. However, some **human** agent outbound paths may pick any **connected** channel as **From** — use one primary address if you need strict alignment for agent replies.
  </Accordion>

  <Accordion title="Quotes And Attachments" icon="quote-right">
    Previous messages in the thread are automatically separated from the new reply. Inbound attachments appear on the conversation. Outbound replies from human agents can include attachments where enabled.
  </Accordion>

  <Accordion title="Security Snapshot (Non-Exhaustive)" icon="shield-check">
    Inbound mail is received securely on your behalf. Outbound replies are sent from your verified domain. For contracts or DPA questions, use your account or legal channel—not this page.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Troubleshooting" icon="wrench" href="/email/troubleshooting">
    Connection failures, missing replies, and common fixes.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    AI to human escalation — applies to email sessions.
  </Card>

  <Card title="AI Actions" icon="bolt" href="/actions/introduction">
    Run tools and workflows from email conversations.
  </Card>

  <Card title="Autopilot And Topics" icon="sliders" href="/handoff/topics">
    Channel-level Autopilot and topic rules.
  </Card>
</CardGroup>

## Replies after a primary-contact change

An agent can change **To** when replying from a native OpenCX email session.
Selecting **Send** makes the new recipient the primary contact while preserving
the same session and email subject. The first transfer email includes earlier
customer-visible history so the new recipient has context.

Thread references and known participants connect later replies to the session.
The original contact can still reply to an older email without becoming the
primary contact again. Receiving new messages depends on the recipients of each
outgoing email; being a historical participant does not automatically copy them.

See [Change an email session's primary contact](/inbox/intro#change-an-email-sessions-primary-contact)
for draft, Cc, preview, and retry behavior.


# Email overview
Source: https://docs.open.cx/email/introduction

Overview of the AI email channel — forwarding setup, shared inbox, Autopilot replies, human handoff, and third-party integrations with Zendesk, HubSpot, and more.

The **email channel** handles support mail through **forwarding**. Customers still write to your public address. **Forward** copies from your mail host. Your AI replies when <Tooltip href="https://platform.open.cx/settings/autopilot">**Autopilot**</Tooltip> allows. Your team sees threads in the **[inbox](https://platform.open.cx/inbox)**.

<Tip>
  New here? Skim this page, then open **[Connect Email](/email/forwarding)** to go live.
</Tip>

## Core Functionality

<AccordionGroup>
  <Accordion title="Ingest and Forward" icon="inbox-in">
    Emails forwarded to OpenCX are picked up automatically. Works with your existing addresses — no migration required.
  </Accordion>

  <Accordion title="AI Responses" icon="robot">
    Your AI replies to customers using the knowledge base and tools you've already set up. **Autopilot** controls which emails get auto-replied.
  </Accordion>

  <Accordion title="Attachments" icon="paperclip">
    Attachments come through on inbound emails. Outbound replies can include attachments too.
  </Accordion>

  <Accordion title="Threading" icon="messages">
    Replies stay in the same email thread your customer started. The [OpenCX dashboard](https://platform.open.cx) is the source of truth — email clients may group threads differently.
  </Accordion>

  <Accordion title="Third-Party Integrations" icon="plug">
    Connect to Zendesk, HubSpot, Salesforce, and others from the [integrations settings](https://platform.open.cx/settings/integrations).
  </Accordion>

  <Accordion title="CRM Copies" icon="copy">
    Quietly copy every reply sent from an inbox to your CRM's inbound address, so it sees both sides of the thread. See [Copy Replies To Your CRM](/email/forwarding#copy-replies-to-your-crm).
  </Accordion>

  <Accordion title="Escalation" icon="user-group">
    <Tooltip href="/handoff/introduction">Escalates to a human agent</Tooltip> when needed — your team picks up right where the AI left off.
  </Accordion>

  <Accordion title="Formatting" icon="paintbrush">
    Outbound replies keep rich formatting (bold, lists, links) and strip anything unsafe. Your customers see clean HTML emails.
  </Accordion>

  <Accordion title="Web Forms And Help Center Emails" icon="rectangle-list">
    Form submissions that forward to your support address are treated as new email conversations automatically — no separate setup required.
  </Accordion>

  <Accordion title="Per-Address AI Behavior" icon="sliders">
    Autopilot and topic rules can be configured at the channel level in [Autopilot settings](https://platform.open.cx/settings/autopilot).
  </Accordion>
</AccordionGroup>

<Note>
  You **forward** mail at your host. Replies send from your <Tooltip href="https://platform.open.cx/settings/domains">**verified domain**</Tooltip>. Thread layout varies by mail client—see [Email Flow](/email/forwarding-rules).
</Note>

## Integration Options

<Tabs>
  <Tab title="Email forwarding">
    **Forward** a copy of mail for your support address to the address from **Connect Email**. Verify the domain. Register the address in your [OpenCX dashboard](https://platform.open.cx). Mail then appears in your inbox.

    <Card title="Connect Email" icon="arrow-right" href="/email/forwarding">
      Step-by-step: domain, address, provider rule, connection test.
    </Card>
  </Tab>

  <Tab title="Third-party integrations">
    Connect helpdesks and CRMs from the [integrations settings](https://platform.open.cx/settings/integrations).

    <AccordionGroup>
      <Accordion title="Zendesk" icon="headset">
        Email conversations sync with [Zendesk](/integrations/zendesk/ticketing-api). When the AI hands off, a ticket is created in your Zendesk Support instance with the conversation and tags. Your agents stay in Zendesk.

        <Note>OpenCX also integrates with [Zendesk Messaging](/integrations/zendesk/sunshine-conversations).</Note>
      </Accordion>

      <Accordion title="Intercom" icon="message">
        Email conversations sync with [Intercom](/integrations/intercom/overview). When the AI hands off, your agents see the full thread in their Intercom inbox.
      </Accordion>

      <Accordion title="Front" icon="inbox">
        Email threads appear in your Front inbox. Handoffs route directly to your Front team with the full AI conversation attached.
      </Accordion>

      <Accordion title="HubSpot" icon="users-viewfinder">
        Conversations sync to [HubSpot](/integrations/hubspot/overview), including email threads. On handoff, your agents pick up in HubSpot with full context.
      </Accordion>

      <Accordion title="Freshchat" icon="comment">
        Connect [Freshchat](/integrations/freshchat/overview) for Freshworks conversations and handoffs.
      </Accordion>

      <Accordion title="Other integrations" icon="grid-2">
        OpenCX also supports [**Salesforce**](/integrations/salesforce/overview), [**Gorgias**](/integrations/gorgias/overview), [**Dynamics 365**](/integrations/dynamics-365/overview), and [**Twilio Flex**](/integrations/twilio-flex/overview). See [All Integrations](/dashboard/introduction) for the current list.
      </Accordion>
    </AccordionGroup>

    <CardGroup>
      <Card title="Zendesk Integration" icon="headset" href="/integrations/zendesk/overview">
        Setup and handoff.
      </Card>

      <Card title="Intercom Integration" icon="message" href="/integrations/intercom">
        Conversation sync and handoff.
      </Card>

      <Card title="HubSpot CRM" icon="users-viewfinder" href="/integrations/hubspot/overview">
        Email sync, contacts, and handoff.
      </Card>

      <Card title="All Integrations" icon="grid-2" href="/dashboard/introduction">
        Browse every supported integration.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Email" icon="paper-plane" href="/email/forwarding">
    Domain verification, provider setup, connection test.
  </Card>

  <Card title="Email Flow" icon="diagram-project" href="/email/forwarding-rules">
    Session matching, threading, and outbound format.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/email/troubleshooting">
    Connection failures, missing replies, and common fixes.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    AI to human escalation — applies to email sessions.
  </Card>
</CardGroup>


# Sending Domains & DNS
Source: https://docs.open.cx/email/sending-domains

Verify the domain OpenCX sends email from — the exact DNS records to add, how verification works, and why a dedicated subdomain protects your main-domain reputation.

Before OpenCX can send email as your address, you verify the domain by adding a few DNS records. The **exact records — names, types, and values — are generated for your domain** under **[Settings → Domains](https://platform.open.cx/settings/domains)** (or via the [domain API](/api-reference/email/get_domains)); this page explains what they are and how to add them.

## Recommended: use a dedicated subdomain

We strongly recommend verifying a **subdomain** (e.g. `mail.yourcompany.com` or `support.yourcompany.com`) rather than your root domain:

* **Reputation isolation.** Sending reputation is tracked per domain. A dedicated subdomain keeps AI-agent and support traffic fully separate from your corporate mail — deliverability issues on one can never affect the other.
* **No conflicts.** The verification records live only on the subdomain, so nothing touches the SPF/DKIM/MX setup of your existing mail.
* **Same display address.** You can still send from any address on the verified domain (e.g. `support@mail.yourcompany.com`), and replies route back through your normal [forwarding setup](/email/forwarding).

## The DNS records

After adding a domain in **Settings → Domains**, you'll see a table of records to create at your DNS provider. Copy each one exactly as shown. The set is:

| Record | Type | Purpose |
| - | - | - |
| SPF | `TXT` (+ `MX` on a `send` subdomain) | Authorizes OpenCX to send mail on behalf of the domain. |
| DKIM | `TXT` | Cryptographically signs outgoing mail so receivers can verify it wasn't altered and really comes from your domain. |

<Note>
  The record **names and values are unique to your domain** — always copy them from the dashboard rather than from documentation or another domain's setup.
</Note>

<Tip>
  **DMARC** is not required for verification, but if your organization enforces a DMARC policy on the root domain, verifying a subdomain (recommended above) means your policy is unaffected. If you want DMARC coverage on the sending subdomain itself, a standard `_dmarc` TXT record with `p=none` is a safe starting point.
</Tip>

## Verifying

<Steps>
  <Step title="Add the domain">
    In **[Settings → Domains](https://platform.open.cx/settings/domains)**, enter the (sub)domain you want to send from. Choose **Sending region**: **EU**, selected by default, or **US**. The region cannot be changed after adding the domain. The required DNS records appear immediately.
  </Step>

  <Step title="Create the records at your DNS provider">
    Add each record with the exact name, type, and value shown. TTL can stay at your provider's default.
  </Step>

  <Step title="Run verification">
    Click **Verify** in the dashboard (or call the [verify API](/api-reference/email/patch_domains_verify)). DNS propagation usually takes minutes but can take up to 48 hours; each record shows its individual status, so you can see exactly which one is still pending.
  </Step>
</Steps>

Once the domain shows **Verified**, you can register sending addresses on it — continue with [Connect Email](/email/forwarding).

## Sending region

The domain list and domain details show the saved sending region when available. Older domains may have no recorded region; adding this setting does not move existing domains.

The [add-domain API](/api-reference/email/put_domains) and the `add_email_domain` MCP tool accept an optional `region`: `eu-west-1` for EU (Ireland), or `us-east-1` for US (North Virginia). Omitting it creates new domains in EU (Ireland). Adding a domain that already exists returns its existing configuration.

## Related Documentation

<CardGroup>
  <Card title="Connect Email" icon="paper-plane" href="/email/forwarding">
    Register your support address and set up forwarding.
  </Card>

  <Card title="Domain API" icon="code" href="/api-reference/email/get_domains">
    Manage domains and read record status programmatically.
  </Card>
</CardGroup>


# Sequence email sender settings
Source: https://docs.open.cx/email/sequence-senders

Control email spacing and daily sending caps for each sequence sender. Use these settings to adjust how your sending addresses process queued emails.

Open **Outbound → Senders** to manage your sequence email addresses. You need permission to manage email senders to change their settings; members with read access can view them.

## Standard sending limits

Each email address has a **Standard limits** toggle, enabled by default:

* **On**: normal spacing between emails, a daily allowance that increases with active sending days, and an automatic pause when the email service asks the sender to slow down.
* **Off**: up to **3 email attempts every 30 seconds**, with no OpenCX daily cap or one-hour throttling pause. Temporary throttling failures remain visible and become eligible for retry after 30 seconds. Rejected attempts count toward the sending pace too.

Changes save automatically and apply across all sequences using that address. Each address has its own setting, even when several addresses use the same sender name. Turning the toggle back on restores the standard controls using the address's existing sending history.

Sequence delays, sending windows, unsubscribes, and authentication or account blocks still apply. The email service may reject an attempt; turning off standard limits does not guarantee delivery or send all queued emails instantly.


# Email troubleshooting
Source: https://docs.open.cx/email/troubleshooting

Fix common email channel issues — connection test failures, missing AI replies, and unwanted auto-replies.

Before debugging, have these ready: your **mail host** (Gmail, M365, …), the **channel status** in your [OpenCX dashboard](https://platform.open.cx), and a **recent message or ticket ID** if available.

<Tip>
  Looking for setup steps? See [Connect Email](/email/forwarding). For routing logic and session matching, see [Email Flow](/email/forwarding-rules).
</Tip>

## Common Troubleshooting Scenarios

| Symptom | Likely cause | What to do |
| - | - | - |
| **Pending a long time** | Rule not delivering to `forwarding@opencopilot.so`, or filters blocking the test | Send a manual message to your support address and verify a copy reaches the forward destination. |
| **Failed after \~5 minutes** | Inbound never showed your registered address in **To** | Inspect headers (BCC-only paths may not match). Fix the rule, then re-run the wizard test. |
| **AI replies to automated or out-of-office emails** | Auto-replies and notifications are forwarded alongside real mail | Block the sender in [**Blocked Contacts**](https://platform.open.cx/settings/autopilot) — add known `noreply@` and `do-not-reply@` domains proactively. |
| **Customer receives duplicate AI replies** | Customer sent multiple messages before the first AI reply arrived | Each new message triggers a separate response. Ask customers to wait for the first reply before sending follow-ups. If duplicates persist on single messages, contact support. |

<Info>
  If the connection test stays **Pending** or ends **Failed**, the problem is almost always **forwarding** or **headers** — not a platform outage on our side.
</Info>

### AI Not Replying — Checklist

Work through in order. Stop at the first match.

1. **Autopilot disabled** — Enable it for email under [Autopilot settings](https://platform.open.cx/settings/autopilot).
2. **Helpdesk permissions** — If you use Zendesk or HubSpot, verify the AI user has **full agent** permissions (not Contributor or Light).
3. **Provider rejected the message** — Check your helpdesk logs for delivery warnings or invalid-comment flags.
4. **Blocked contact or domain** — Confirm the sender is not on your [blocklist](https://platform.open.cx/settings/autopilot).
5. **AI chose not to reply** — Low-confidence answers, prohibited topics, and human-assigned sessions do not produce an outbound email.

## What Each Message Must Include

Messages that don't meet these requirements are silently skipped.

<CardGroup>
  <Card title="New emails" icon="envelope-circle-check">
    The **To** field must contain the support address you registered in the dashboard (e.g. `support@yourcompany.com`).
  </Card>

  <Card title="Replies to existing threads" icon="reply">
    Must come from the same sender as the original email **and** include the session token — either `[12345]` in the subject or `Ref: #12345` in the body.
  </Card>
</CardGroup>

## Expectations

| Area | Detail |
| - | - |
| **After mail hits the shared forwarding address** | Allow about **one minute** after forwarding. |
| **Connection test (UI)** | May take up to **\~5 minutes** before timeout. |
| **Large volumes** | Large volumes may take multiple cycles to process. |
| **Session auto-resolution** | Email conversations with no activity auto-resolve after a configurable window. Contact support to adjust your org's threshold. |

## Impact Of Misconfiguration

Misconfigured rules can send the wrong mail into **OpenCX** for an address you registered — prefer **dedicated** support addresses. **DNS and mailbox ownership** remain your responsibility.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Email" icon="paper-plane" href="/email/forwarding">
    Re-check domain, provider setup, and connection test.
  </Card>

  <Card title="Email Flow" icon="diagram-project" href="/email/forwarding-rules">
    Re-check session matching, threading, and outbound format.
  </Card>

  <Card title="Autopilot And Topics" icon="sliders" href="/handoff/topics">
    Verify channel-level Autopilot and topic rules.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    AI to human escalation — applies to email sessions.
  </Card>
</CardGroup>

## Recipient changes and failed replies

* **The primary contact changed, but the email failed:** the transfer remains saved.
  Use **Retry email** on the failed message. Do not create another copy while its
  delivery is uncertain.
* **Retry is unavailable after redaction:** saved emails may quote earlier session
  content, so redaction disables existing retries in affected sessions. Review the
  remaining history and compose a new reply if needed. An email already delivered
  to a recipient cannot be recalled by redacting it in OpenCX.
* **The composer says the primary contact changed:** another agent updated the
  session after your draft began. Review To and Cc, then use the reviewed recipients
  before sending a new reply.
* **The previous contact is not receiving updates:** changing To does not put them
  in Cc automatically. Add them explicitly if they should receive the next email.
* **An earlier participant replied, but AI did not respond:** their reply can appear
  in the same session, but automated responses are driven by the current primary contact.
* **To cannot be edited:** this feature requires a connected native OpenCX email
  inbox and session-write permission. It does not apply to integration-backed
  sessions or campaign mailboxes.


# Features
Source: https://docs.open.cx/features

| Platform | Features | |----------|----------| | Zendesk | Full ticket management, macros, agent handoff, native integration | | Intercom | Inbox integration…

## 🤖 Core AI Engine (Agent 5)

### AI Capabilities

* **Train Once, Deploy Everywhere**: Single training session, deploy across all channels
* **77% Average Automation Rate**: Industry-leading automated resolution rate
* **95%+ Accuracy**: High precision with confidence thresholds
* **Multi-step Actions**: Execute complex workflows through API calls
* **Multi-model Engine**: Uses multiple AI models for best results
* **Continuous Learning**: Improves automatically over time

### Observability & Transparency

* Every Decision Explained with reasoning traces
* Confidence scores for every response
* Source citations for responses
* Real-time Performance Metrics
* Conversation Replays
* Error Detection & Alerts
* Evaluation Dashboard

***

## 📱 Communication Channels

### Voice AI

* **International Numbers**: Local phone numbers in 100+ countries
* **Custom Voices**: Voice cloning via ElevenLabs
* **High Concurrency**: Handle up to 500 simultaneous calls
* **Multi-lingual Support**: 6+ languages with native pronunciation
* **SIP Trunking**: Connect to any phone system
* **API-First Design**: Build custom voice workflows
* Natural conversations with intelligent routing
* Seamless handoffs to human agents

### Web Chat Widget

* One-line code embedding
* Fully customizable branding
* AI Vision & Memory (understands images)
* Handles complex requests (returns, account updates)
* Rich Media Support (images, videos, files)
* Interactive UI Elements (buttons, forms, cards, carousels)
* User Authentication & Personalization
* Human + AI Collaboration with seamless handoffs
* Proactive Chat triggers based on user behavior
* Mobile-responsive design

### Email Support AI

* Custom domain support (your brand)
* Attachment processing (PDFs, screenshots, invoices)
* Minutes response time (vs 24+ hours)
* Invisible AI-to-human handoffs
* Full email history memory
* Multiple inbox management (support@, sales@, billing@)
* Smart routing to appropriate teams

### WhatsApp AI

* Voice note transcription and responses
* Image/screenshot understanding
* 98% open rates for proactive outreach
* Full conversation context retention
* Human takeovers without disruption
* Proactive outreach capabilities
* Multi-language support

### Slack Integration

* @mention for instant answers
* Private DM support for sensitive questions
* Company knowledge indexing
* Works in channels and threads
* Automated alerts & updates
* Personal AI assistant for every team member

### Social Media AI

* Instagram DM Automation
* Facebook Messenger Support
* Unified Social Inbox
* Rich visual responses (images, videos, GIFs, carousels)
* Story & Comment Monitoring
* Seamless human handoffs

***

## 🔗 Integrations

### Ticketing Systems (Helpdesks)

| Platform | Features |
| - | - |
| **Zendesk** | Full ticket management, macros, agent handoff, native integration |
| **Intercom** | Inbox integration with conversation routing |
| **Freshdesk** | Ticket automation and SLA management |
| **HubSpot Service Hub** | Unified customer service with CRM context |
| **Salesforce Service Cloud** | Enterprise-grade case management |
| **Twilio Flex** | Programmable contact center integration |
| **Front** | Shared inbox integration |
| **Open Helpdesk** | Native AI-first helpdesk solution |

### Training Sources / Knowledge Bases

| Source | Description |
| - | - |
| **Web Crawler** | Automatically crawl and index websites |
| **Notion** | Sync pages, databases, workspaces |
| **Confluence** | Import spaces and documentation |
| **Google Docs** | Connect documents and shared drives |
| **Google Sheets** | Import structured data |
| **Zendesk Help Center** | Sync articles and knowledge base |
| **Intercom Articles** | Import help center articles |
| **Freshdesk KB** | Sync solution articles |
| **GitBook** | Import documentation and guides |
| **GitHub** | Sync README files and wikis |
| **Slack** | Learn from channel history and threads |
| **Airtable** | Connect bases and tables |
| **Coda** | Sync docs and structured content |
| **Dropbox** | Import documents and files |
| **OneDrive** | Connect Microsoft documents |
| **SharePoint** | Sync enterprise document libraries |
| **Asana** | Import project documentation |
| **Monday.com** | Sync board data and docs |
| **HubSpot KB** | Import knowledge base articles |
| **MongoDB** | Import document collections |
| **Snowflake** | Connect data warehouse |
| **BigQuery** | Sync Google data warehouse |
| **CSV/Excel** | Import spreadsheet data |
| **REST API** | Custom API integration |

### CRM Systems

| CRM | Status |
| - | - |
| **HubSpot CRM** | Full contact sync, deals, activity logging |
| **Salesforce** | Enterprise CRM with case and account sync |
| **Pipedrive** | Sales pipeline integration (Beta) |
| **Zoho CRM** | Contact and deal synchronization (Limited) |

### E-commerce

| Platform | Features |
| - | - |
| **[Shopify](/integrations/shopify/overview)** | Order lookup, product search, customer metadata enrichment |

### IT & DevOps

| Tool | Features |
| - | - |
| **Jira** | Create and track issues from support conversations |

### Automation & Connectivity

| Tool | Description |
| - | - |
| **Zapier** | Managed integration with 5,000+ apps |
| **Webhooks** | Custom event-driven integrations |
| **REST API** | Build custom integrations |

***

## 📊 Analytics & Insights

### Customer Insights

* **Voice of Customer Analysis**: Understands what drives support volume
* **Smart Clustering**: Groups similar issues together
* **Auto-Generated Jira Tickets**: Deep research agent creates complete tickets
* **Team Competition & Gamification**: Leaderboards for resolving insights
* **Cross-Channel Analysis**: Unified insights across all channels
* **Root Cause Identification**: Not just symptoms—actual causes
* **Customer Impact Analysis**: Affected user count, priority levels
* **Weekly Impact Reminders**: Automated follow-ups

### API Endpoints for Insights

* `GET /insights` - Retrieve all customer insights
* `GET /insights/:id` - Get specific insight details
* `POST /insights/:id/resolve` - Mark as resolved
* `POST /insights/:id/assign` - Assign to team

### Knowledge Gap Detection

* **Handoff Pattern Analysis**: Tracks which knowledge causes escalations
* **Multi-Channel Gap Detection**: Detect gaps across all channels
* **AI-Suggested Content**: Drafts documentation from successful responses
* **Automatic Prioritization**: By impact and frequency
* **Cross-Channel Gap Clustering**: Unified gap analysis
* **Knowledge Base Autopilot**: Self-maintaining documentation

***

## ⚙️ Automation & Workflows

### Agentic Workflows

* **Drag-and-Drop Builder**: Visual workflow builder, no code required
* **15 Triggers Available**: Form submissions, webhooks, CRM updates, time-based, email received, etc.
* **25 Actions to Execute**: AI phone calling, email sequences, WhatsApp, CRM integration, conditional logic, etc.
* **Multi-Party Orchestration**: Coordinate complex communication
* **Conditional Logic & Branching**: Dynamic workflow paths
* **Human Behavior at Scale**: Mimics human communication patterns

### Available Triggers

* Form Submissions
* WhatsApp Webhooks
* CRM Updates
* Time-based Triggers
* Email Received
* +10 more triggers

### Available Actions

* AI Phone Calling
* Outbound Email Sequences
* WhatsApp Messages
* CRM Integration
* Conditional Logic
* Wait for Response
* AI Decision Making
* Data Transformation
* +17 more actions

***

## 📤 Outbound Sequencing

### Capabilities

* **AI WhatsApp Sequences**: Personalized messages at scale
* **AI Phone Call Campaigns**: Automated calling with natural conversations
* **SMS with AI Responses**: Two-way SMS conversations
* **AI Email Sequences**: Multi-step email campaigns

### Features

* Bulk Contact Import (hundreds of thousands)
* Multi-Channel Sequences
* AI-Powered Personalization
* Response-Based Branching
* API & UI Access

### API Endpoints

* `POST /sequences` - Create multi-step sequences
* `PUT /sequences/:id/start` - Activate sequence
* `GET /sequences/:id` - Retrieve sequence details
* `PATCH /sequences/:id` - Modify steps, delays, targeting
* `PUT /sequences/:id/cancel` - Stop running sequence
* `POST /sequences/continuous/contacts` - Add contacts

***

## 📋 Pre-built Templates

### Support Excellence

* Automate support tickets quality assurance
* Automate following up with voice calls
* Automate Slack alerts based on issues
* Automate skill-based routing
* Automate ticket prioritization
* Automate ticket sentiment analysis
* Automate escalating to the right team
* Automate phone calling from email

### Revenue Automation

* Automate up-sells from support tickets
* Automate cart recovery

### Custom Field Automation (per helpdesk)

* Zendesk custom fields fill up
* HubSpot custom fields fill up
* Salesforce custom fields fill up
* Intercom custom fields fill up
* Freshdesk custom fields fill up
* Twilio Flex custom fields fill up

### Review & Reputation

* Automate replying to Trustpilot reviews
* Automate requesting reviews when customer is happy

### Pre-Sales

* Automate pre-sales qualification

### AI Phone Call Templates

* Appointment reminders
* Payment collection
* Delivery notifications
* Customer surveys
* Renewal reminders
* Win-back campaigns
* Order confirmations
* Proactive outreach campaigns

### Proactive Intelligence Templates

* Detect churn risk → Proactive retention call
* Identify high-value lead → Priority sales routing
* Detect expansion opportunity → Account growth call
* Identify payment failure → Recovery call
* Detect usage milestone → Upgrade trigger
* Identify referral opportunity → Request referral
* Detect competitor evaluation → Competitive win campaign
* Identify free trial ending → Conversion call
* Detect bulk purchase intent → Enterprise sales handoff
* Identify feature gap → Product-led upsell

***

## 🔒 Security & Compliance

### GDPR Compliance

* **Infrastructure**: Frankfurt, Germany (EU)
* **AI Processing**: OpenAI models hosted on Microsoft Azure in Sweden (EU). Your data is never used for training
* **Data Residency**: Customer data is stored in the EU, and AI processing runs in the EU

### Data Security

* **Encryption in Transit**: TLS 1.3 for all data transmission
* **Encryption at Rest**: AES-256 for sensitive data

### GDPR Rights Supported

* ✓ Right to access
* ✓ Right to rectification
* ✓ Right to erasure
* ✓ Right to data portability
* ✓ Right to restrict processing
* ✓ Right to object
* ✓ Rights related to automated decision-making

### Certifications (In Progress)

* AICPA SOC 2 (In Progress)
* ISO 27001 (In Progress)
* GDPR (Live)

### Trust Center

* Available at: [https://trust.open.cx](https://trust.open.cx)
* Subprocessors list available

***

## 🏢 Industries Supported

| Industry | Use Cases |
| - | - |
| **Financial Services** | Account inquiries, fraud reports, payment questions, compliance |
| **Healthcare** | Appointment scheduling, insurance verification, prescription refills, HIPAA compliance |
| **Mobility & Transportation** | Trip dispute resolution, refund automation, rider/driver support |
| **Technology & SaaS** | Onboarding, troubleshooting, API support |
| **Travel & Hospitality** | Reservations, weather cancellations, equipment questions, 100+ languages |

***

## 🛠️ Free Tools

| Tool | Description |
| - | - |
| **ROI Calculator** | Calculate potential savings |
| **AI Readiness Assessment** | Evaluate your organization's AI readiness |
| **Team Size Calculator** | Plan optimal team structure |
| **Budget Planner** | Support budget planning |
| **Benchmark Tool** | Compare against industry benchmarks |
| **AI Adoption Guide** | Step-by-step adoption guidance |

***

## 🚀 Implementation

### Setup Process

1. **Connect your helpdesk** - Works with Zendesk, HubSpot, Freshdesk, Intercom, Salesforce, etc.
2. **Add your training data** - Connect documentation, wikis, guides, knowledge base
3. **Connect your systems** - Link backoffice tools and APIs
4. **Monitor and improve** - Track performance and refine over time

### Implementation Details

* **Setup Time**: \< 1 hour with implementation experts
* **Integration Time**: Under 1 hour
* **Routing Control**: Route 100% or 10% of support—fully flexible
* **Existing Reporting**: All Zendesk/helpdesk reporting remains intact

***

## 💰 Pricing

* **Outcome-based pricing** - Pay based on results
* Enterprise-ready with custom solutions available

***

## 📞 Support & Resources

* **Documentation**: [https://docs.open.cx/api-reference](https://docs.open.cx/api-reference)
* **Blog**: [https://blog.open.cx](https://blog.open.cx)
* **Status Page**: [https://status.open.cx](https://status.open.cx)
* **GitHub**: [https://github.com/opencx](https://github.com/opencx)
* **LinkedIn**: [https://www.linkedin.com/company/opencx/](https://www.linkedin.com/company/opencx/)

***

## 🏆 Customer Success Stories

| Company | Results |
| - | - |
| **Mollie** | 60%+ automation, 250K+ businesses, 24/7 in 8 languages |
| **TicketSwap** | 67% automation, 19M users, ATH CSAT |
| **MoneyGram** | 70% automation, 55M customers, 200+ countries |
| **Trunkrs** | 80% automation, 4.8/5 rating, 60K+ reviews |
| **OTO** | 77% automation, 90%+ CSAT |
| **More.com** | 67% automation, 30M tickets, ATH CSAT |
| **FareHarbor** | 70% automation, 20K+ operators, 4.8★ rating |
| **Qoyod** | 77% automation, 25K+ businesses |
| **One Car Now** | 60% automation, 7.5K vehicles, 90min avg response |
| **De Online Drogist** | 73% automation, 25+ actions, 40K+ products |
| **CookingLife** | 70% automation, 1M+ customers, 10K+ products |


# Human Handoff
Source: https://docs.open.cx/handoff/introduction

Human handoff transfers a live conversation from the AI to a human agent. It happens automatically when the AI decides it cannot resolve the issue, or when the customer explicitly asks for a human.

Human handoff transfers a live conversation from the AI to a human agent. It happens automatically when the AI decides it cannot resolve the issue, or when the customer explicitly asks for a human.

For the full list of configurable behaviors, see [Handoff Settings](/handoff/settings).

## When handoff happens

By default, handoff is triggered in any of these situations:

<CardGroup>
  <Card title="Explicit request" icon="user">
    The customer asks to speak with a human agent.
  </Card>

  <Card title="AI decision" icon="robot">
    The AI determines it cannot properly resolve the situation.
  </Card>

  <Card title="Frustration" icon="face-frown">
    The customer shows signs of frustration during the conversation.
  </Card>

  <Card title="Forbidden topic" icon="shield-halved">
    The conversation touches a topic configured for mandatory handoff.
  </Card>
</CardGroup>

Each of these triggers can be tuned or disabled individually. See [Handoff Settings](/handoff/settings).

## Handoff across channels

Handoff works the same way conceptually on every channel — the AI stops responding, a human takes over, and the full conversation history is preserved. The surface differs per channel.

### Web chat

* AI stops responding in the same thread.
* A human agent takes over from the inbox.
* Full history is preserved for the agent and the customer.

The widget keeps human replies in the same session. There is no `onHandoff` widget option. Headless integrations can observe session state with `useSessions`; `hooks.onMessageReceived` reports newly delivered messages and is not an immediate handoff event. See [widget session behavior](/widget/conversation-sessions#what-handoff-looks-like-in-the-widget).

### Phone calls

* The AI transfers the call to a fallback phone number configured on the phone agent itself.
* Call history and context (including the AI-generated summary) are preserved on the session.

<Note>
  Phone uses a per-agent handoff configuration rather than the org-wide [Handoff Settings](/handoff/settings). The transfer switches, office hours, and data collection toggles on that page apply to text-based channels (web, email, WhatsApp, SMS, Slack) — not voice calls.
</Note>

### Email

* The AI assigns complex threads to a human agent.
* A conversation summary and the full thread context are attached.

### Slack

* The AI posts the conversation into your designated Slack support channel.
* Your team replies from Slack and the customer receives the response on their original channel.

### WhatsApp

* The AI stops responding in the same WhatsApp thread.
* A human agent continues the conversation. No additional setup required.

### SMS

* The AI stops responding on the same phone number.
* A human agent takes over the thread seamlessly.

## Next steps

<CardGroup>
  <Card title="Handoff Settings" icon="sliders" href="/handoff/settings">
    Configure transfer behavior, office hours, data collection, and more.
  </Card>

  <Card title="Forbidden topics" icon="shield-halved" href="/handoff/topics">
    Define topics that always trigger a human handoff.
  </Card>
</CardGroup>


# Handoff Settings
Source: https://docs.open.cx/handoff/settings

Configure human transfers and Team in the loop. Set up private requests for team help, office hours, takeover behavior, and historical filtering.

This page is a complete reference for every option on the **Settings → Handoff** page in your dashboard. If you are new to handoff, start with the [Human Handoff overview](/handoff/introduction).

## AI to human transfer behavior

Controls when the AI decides to hand off a session. Each behavior has its own switch, and changes apply to new messages as soon as you save.

| Setting | What it does |
| - | - |
| **Enable Handoff** | Master switch. When off, the AI never transfers to a human regardless of the other switches. |
| **Handoff on Human Request** | Transfer when the customer explicitly asks for a human agent. |
| **Require Problem Statement** | Before transferring, the AI must understand the customer's problem clearly. |

<Warning>
  Disabling **Handoff on Human Request** means the AI will ignore messages like "let me talk to a human". This is almost never what you want — customers expect that option to work, and blocking it is a common source of CSAT complaints. Only turn it off if you have a specific business reason and a separate escalation path.
</Warning>

## Within office hours

Customize the AI's message when it hands off during your configured office hours. The text you provide here is used as instructions for the AI — the AI will phrase it naturally in the conversation's language.

Example:

> I'll transfer you to our support team now. They'll be with you shortly.

Leave blank to use the AI's default wording.

## Outside office hours

Two settings control behavior when a handoff is needed outside office hours.

### Allow handoff outside office hours

<ParamField type="boolean">
  When enabled, conversations can still be transferred to human agents outside office hours. Agents will see the handoff when they're next online.
</ParamField>

When disabled, the AI will not transfer outside of office hours — even on explicit request.

### Outside hours AI instructions

Custom instructions used when the AI needs to respond to a handoff situation outside office hours. The wording depends on whether you allow handoff outside hours:

* **If allowed:** let the customer know the transfer happened but a response may be delayed.
* **If not allowed:** explain that the support team is unavailable and will reply during office hours.

Example (handoff allowed outside hours):

> I'll transfer you to our support team, but please note that since we're outside office hours, their response might be delayed.

Example (handoff not allowed outside hours):

> Our human support team is currently unavailable as we are outside office hours. They will be back during regular business hours.

<Info>
  Office hours are configured in **Settings → Office Hours**. The handoff settings read from that configuration.
</Info>

## Handoff summary language

When a handoff happens, the AI generates a short summary of the conversation for the human agent. This section controls the language that summary is written in.

<ParamField type="boolean">
  When enabled, the summary is written in the same language the conversation is happening in.
</ParamField>

Disable this toggle to pin the summary to a specific language regardless of the conversation language — useful when your support team only reads one language but your customers chat in many.

## Team in the loop

When the AI needs information, an approval, or an action from your team, **Team in the loop** lets it ask privately in Inbox and stay with the customer. It posts an internal note, mentions teammates, adds the **AI needs help** tag, and tells the customer it is checking with the team.

### Enable team help

1. Open [Settings → Advanced](https://platform.open.cx/settings/ai-features).
2. Turn on **Team in the loop**. It is off by default, and the switch saves automatically. You need permission to edit AI Autopilot settings.
3. Have teammates [answer the help note in Inbox](/inbox/intro#answer-an-ai-help-request).

If the page shows **Contact us** instead of a switch, request access for your workspace. Installing a newer widget alone does not enable the feature.

Use team help for text sessions your team handles in Inbox. This includes custom email addresses handled in Inbox even when other sessions go to an external helpdesk. Sessions handled in the external helpdesk and app reviews are excluded.

### Who receives the request

Mentions follow your skills routing. The AI identifies the skill it needs and mentions members of the session's team who have it. If there is no match, it looks for that skill across the workspace, then falls back to the session's team, then to everyone with access to the session.

While a request is unanswered, a new question joins the existing note thread instead of opening another request. Reply in that thread to give the AI the information it needs. The AI follows up with the customer and quotes the question it is answering. A direct reply to the customer also answers the request; the AI resumes on the customer's next message.

### Replies, takeover, and history

On eligible AI-assigned sessions, typing or sending a reply keeps the AI assigned. This applies even when there is no open help request. The [first-reply dialog and takeover controls](/inbox/intro#reply-without-taking-over) let you choose whether to keep AI available or handle the session yourself.

Filter Inbox by **AI needs help**, or save a view with that tag, to review requests for team help. The tag stays after replies, takeover, handoff, and closure. It records that help was requested; it does not mean an answer is still pending. Include closed sessions in your filters when reviewing past requests.

Handoff settings continue to control transfers. With handoff enabled, requests for a person and other configured transfer conditions still trigger handoff. With handoff disabled, the AI can ask the team for help while staying on the session. While AI remains assigned, closure, billing, and reporting follow the usual AI-session behavior.

<Note>
  Widget v4 can still receive the replies when team help is enabled for the workspace. The quote display and Companion avatar controls described in the [v5 migration guide](/widget/migrate-to-v5#team-replies-and-quoted-messages) require Widget `5.0.0-beta.10` or later. Internal help notes stay in Inbox.
</Note>

## Forbidden topics

Certain topics always trigger a handoff, regardless of the switches above. These include legal matters, financial details, and other sensitive categories.

Forbidden topics are managed in **Settings → AI Autopilot**, not on the Handoff page. See [Unapproved Topics](/handoff/topics) for the full list and how to configure your own.

## Data collection

Before the AI transfers a conversation to a human, it can be required to collect specific information from the customer. This saves the human agent from asking for it again.

<ParamField type="boolean">
  The AI will collect the customer's email address before handing off, unless it's already available from the customer's profile.
</ParamField>

<ParamField type="boolean">
  The AI will collect the customer's name before handing off, unless it's already available from the customer's profile.
</ParamField>

<Note>
  These toggles save immediately — no need to click "Save" at the top of the page.
</Note>

## Saving changes

Most settings on this page only persist after you click **Save** at the top right. The two data collection toggles are the exception — they save on toggle. If you navigate away without saving, unsaved changes are lost.


# Handoff Topics
Source: https://docs.open.cx/handoff/topics

Tell the AI which topics to never handle — refunds, legal, safety — and have every matching conversation routed straight to a human agent.

Some conversations should never get an AI reply — refund requests, legal questions, safety incidents. **Handoff topics** are the list you hand the AI as "don't touch." Anything the AI classifies into that list is immediately handed off to a human agent with full context.

<Tip>
  Configure topics in **[Settings → Autopilot](https://platform.open.cx/settings/autopilot)** under the **Autopilot topics** section.
</Tip>

## How It Works

<Steps>
  <Step title="You list topics in plain language">
    One topic per line. Write them the way a teammate would — *"refund requests"*, *"billing disputes"*, *"account cancellation"*. No keywords or regex.
  </Step>

  <Step title="The AI classifies each conversation">
    On every inbound message, the AI reads the conversation against your topic list. Matching conversations are flagged as "do not auto-reply."
  </Step>

  <Step title="The handoff fires">
    A matched topic triggers the same handoff flow as any other escalation — see [Human Handoff](/handoff/introduction). The full conversation history, any AI-gathered context, and the matched topic are preserved for the agent.
  </Step>
</Steps>

<Note>
  Handoff topics control **whether the AI replies**, not which tools the AI can call. Per-action scoping lives on the action itself — see [segment restrictions](/actions/build-an-action#segment-restrictions).
</Note>

## Good Topics To Start With

<AccordionGroup>
  <Accordion title="Money movement" icon="money-bill-transfer">
    *Refund requests, chargeback disputes, payment method changes.* High-cost mistakes if the AI gets policy wrong.
  </Accordion>

  <Accordion title="Legal and compliance" icon="scale-balanced">
    *GDPR or privacy requests, account deletion under law, subpoenas, anything a lawyer should see.*
  </Accordion>

  <Accordion title="Safety and harm" icon="circle-exclamation">
    *Threats, self-harm mentions, reports of abuse.* Never a good outcome if the AI auto-resolves.
  </Accordion>

  <Accordion title="VIP and enterprise accounts" icon="crown">
    *If a named-account manager should be the first line of contact,* list the account type or segment in your topics.
  </Accordion>
</AccordionGroup>

## Good To Know

<AccordionGroup>
  <Accordion title="Start narrow, widen as needed" icon="magnifying-glass">
    Add topics as your agents surface recurring "the AI should not have replied to this" tickets — not upfront out of caution. Too broad a list means everything hands off and the AI has nothing left to do.
  </Accordion>

  <Accordion title="Review monthly" icon="calendar-check">
    Product and policy shift. A topic that was too risky for the AI in January may be safe by July. Drop topics once the knowledge base and actions cover them.
  </Accordion>

  <Accordion title="Per-channel behavior" icon="grid-2">
    Handoff topics apply to every channel the AI replies on — widget, email, SMS, WhatsApp, phone. One list, one classification model.
  </Accordion>
</AccordionGroup>

## Configure

<Steps>
  <Step title="Open Autopilot settings">
    Go to **[Settings → Autopilot](https://platform.open.cx/settings/autopilot)** and scroll to the **Autopilot topics** section.
  </Step>

  <Step title="Add topics">
    Type each topic on its own line. Save.
  </Step>

  <Step title="Verify">
    Send a test message matching a listed topic from a real channel. Confirm the AI stays silent and the conversation appears in the [inbox](https://platform.open.cx/inbox) as handed off.
  </Step>
</Steps>

***

## Related Documentation

<CardGroup>
  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    What happens after a topic match — the full escalation flow.
  </Card>

  <Card title="Handoff Settings" icon="sliders" href="/handoff/settings">
    Tune transfer behavior, office hours, and data collection.
  </Card>

  <Card title="AI Actions" icon="bolt" href="/actions/introduction">
    Restrict specific tools by segment instead of by topic.
  </Card>

  <Card title="Autopilot Mode" icon="robot" href="/handoff/settings">
    Set how aggressively the AI replies overall.
  </Card>
</CardGroup>


# Articles
Source: https://docs.open.cx/help-center/articles

Write, version, publish, and AI-generate help center articles that ship to your public site and train the AI at the same time.

Help Center articles are the long-form content customers read on your public site and the AI retrieves from at answer time. Every article lives in a category, supports every language you've enabled, and keeps a version history per language.

<Tip>
  Open an article from [**Help Center**](https://platform.open.cx/help-center) — click a category in the sidebar, then pick or create an article.
</Tip>

## Lifecycle

An article has a **source version** (the original-language content you write) and a **locale version** per enabled language (translations).

* **Draft** — changes not yet published. The public site shows the previously published version (or hides the article if there's never been one). The AI does not train on drafts.
* **Published** — the version is live on the public site and in the AI's training index.
* **Updated** — editing a published article starts a draft on top of it. Publishing the draft supersedes the live version; the old version stays in history so you can roll back.

Translations follow the same model: each language has its own published/draft state so you can ship an English update before translations are reviewed.

## Drafting and publishing

* **Saves as you type.** There is no Save button. Every pause writes your changes to the article's draft in the language you are editing; the word in the toolbar shows *Saving…*, *Draft* or *Live*.
* **One shared draft per article and language.** Everyone on the team edits the same draft. If someone else saves it while you have unsaved edits, a banner lets you **Reload** their version or **Keep editing** and overwrite it.
* **Publish when ready.** **Publish** (or ⌘⇧P) saves the draft as a new version and makes it live. Nothing readers see changes until then.
* **Status at a glance.** Every article in the sidebar carries its status in the language you are viewing: a green dot when it is **Live**, **Live · edited** when the live article has unpublished changes, **Draft**, **Unpublished**, **Translating…** while a translation is being written, and **Not translated** when nothing exists in that language yet. With an article open, the language menu shows the same status for every language, so you can see where a translation is missing before you switch.
* **Topics.** The sidebar shows one topic tree per language; each topic shows how many subtopics and articles it holds. Drag topics and articles to reorder or nest them (by default a move is made in every language; see [Categories](/help-center/categories#reorder)), and use the row menu for **Edit**, **Add subtopic**, **Add article**, **Move to** (pick the destination topic from the list, or search for it) and **Delete**.
* **Several Help Centers.** [**Help Center**](https://platform.open.cx/help-center) opens the one you were in last. Click its name at the top of the sidebar to switch to another one or create a new one.
* **Keyboard.** ⌘S saves a version, ⌘⇧P publishes, ⌘B hides the sidebar; the search box above the tree finds any topic or article.

## Content format

Articles are written in a rich-text editor and stored as HTML, so what you see is what the help site and the public API return. Type `[[` to link to another article in the same Help Center. Press **Enter** after the title to carry on into the body. Languages written right to left, such as Arabic and Hebrew, are edited right to left.

Document actions and formatting controls share one panel that stays in place while you scroll. Use **Text style** for headings and lists, the alignment control to align a paragraph, and **More formatting** for colors and highlights. Select text to format it, or choose a style at the caret before typing. **Undo** and **Redo** are available directly in the formatting row. Wider editors also show **Strikethrough**, **Inline code**, **Text color**, **Highlight**, and **Clear formatting** directly; as space narrows, these controls move into **More formatting** (⋯). Type `/` to insert blocks from the keyboard. An emoji name between colons, `:tada:` for example, turns into the emoji as you type it.

The **Insert** menu adds a table, checklist, quote, code block or divider, a **Callout** (note, tip or warning), a **Collapsible section**, numbered **Steps**, an **Image**, or a **Video**. Collapsible sections stay open while you edit; readers can expand them on the public site. To remove one, click inside it and choose **Delete section** in the controls that appear above it. **Backspace** removes an empty section; at the start of a populated section title, it selects the whole section first, so a second **Backspace** deletes it. **Undo** restores deleted sections.

**On this page** lists your article headings beside the document and highlights the section you are reading. Select a heading to jump to it. The outline updates as you write and becomes a compact menu above the article on smaller screens. Add a heading with **Text style** or `/` to start an outline.

Images go in from **Insert → Image** or **/ Image**, by pasting, or by dropping a file. Select an image for its actions: align it left, centre or right (a full-width image has nowhere to go), **Original size** after a resize with the corner handle, **Replace image**, **ALT** for the description screen readers and search engines use, and **Place in the text**, which turns it into an icon at text height at the end of the nearest line of text above it — the last item of a list counts — or at the start of the line below when there is none above. An icon offers **Show on its own line** to make it a figure again. An image that shares a line with text is an icon on the help site too. Inside a table, the handles above a column or beside a row add, remove and merge cells; drag a column boundary to resize it. Click a link to edit it; **⌘-click** (**Ctrl-click** on Windows and Linux) opens it in a new tab.

Videos from YouTube, Vimeo, Loom and Wistia go in from **/ Video**: paste the video's link and it plays inside the article. Pasting a video link onto an empty line does the same. Select a video to delete it. Unlisted Vimeo videos work with their full link, including the part after the video number. YouTube videos play in privacy-enhanced mode, so viewers aren't tracked until they press play.

Over the public API the body is the `content_html` field. Send the whole fragment when replacing a body, or omit it to change only the article's metadata — see [Update an article](/api-reference/help-center/articles/update).

### Path and search text

Open **Path & search settings** from the **⋮** menu on any article to set how it appears publicly:

| Field | What it controls |
| - | - |
| **Path** | The URL segment — e.g. `reset-password`. Generated from the title; override when you want stable URLs. |
| **Search title** | Replaces the article title in search engine results. Use when you want a different length or phrasing. |
| **Search description** | The summary search engines show under the title. |

These are part of the draft, per language: they go live when you publish.

## Version history

Every publish, and every **Save as version** (⌘S), writes a version you can go back to.

* **Open history** — click the word in the toolbar that says where the text stands: **Draft** (unpublished changes), **Saved** (a newer version than the live one), **Live**, **Unpublished** or **New**. It lists every saved version of the language you are viewing, with who saved it and when, and who published the live one. Writes made through the API name the API key; automatic translations are marked as such.
* **Roll back** — pick a version and click **Restore**. The content loads into your draft; publish when you're ready.
* **Discard draft** — goes back to the newest saved version.
* Restore and Discard both ask before they replace your unpublished changes. Rolling back does not delete newer versions — publishing the restored content creates another version on top.

## Generate from a resolved session

OpenCX can draft a new article from the transcript of a resolved session.

<Steps>
  <Step title="Open a resolved session">
    In [**Inbox**](https://platform.open.cx/inbox), open any resolved session. The right sidebar has a **Generate Help Center article** action.
  </Step>

  <Step title="Pick destination">
    Select the Help Center and the category the article should land in.
  </Step>

  <Step title="Review the draft">
    OpenCX writes a structured article — title, summary, body — and creates it as a draft in the category you chose. Nothing is published and nothing trains the AI yet.
  </Step>

  <Step title="Edit and publish">
    Open the article from the Help Center, edit as needed, and publish.
  </Step>
</Steps>

## Good to know

<AccordionGroup>
  <Accordion title="Publishing an article also trains the AI" icon="brain">
    Every published article is indexed for retrieval at answer time. There's no separate "sync to AI" toggle — publish is the trigger, unpublish is the removal.
  </Accordion>

  <Accordion title="Translations publish independently" icon="language">
    English and French versions of the same article have separate publish states. You can ship the English update today and wait on the French translation until tomorrow without blocking either. See [Translations](/help-center/translations).
  </Accordion>

  <Accordion title="Deleting or unpublishing warns about links from other articles" icon="link">
    Articles link to each other by id, so a link survives moves and renames but breaks when its target is deleted or unpublished. Before you confirm either, the dialog lists the articles that link to this one, with the languages each is live in, and any unsaved draft that still carries the link. Open one from the list to fix it first, or go ahead: nothing is blocked. The public API and the Companion expose the same list as **List backlinks**.
  </Accordion>

  <Accordion title="Delete can be undone" icon="trash">
    Deleting an article removes it from the public site, from the AI's training index, and from the editor in every language, but keeps its content and version history. The confirmation toast offers **Undo**; the article comes back at the same address, with its history intact — and if it was published, it is live and back in the AI's training index right away. Use unpublish if you only want the article off the site.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Categories" icon="folder-tree" href="/help-center/categories">
    Group articles for navigation and bulk actions.
  </Card>

  <Card title="Translations" icon="language" href="/help-center/translations">
    Multi-language, glossary, manual-edit protection.
  </Card>

  <Card title="Help Center overview" icon="book-open" href="/help-center/overview">
    Everything the Help Center does.
  </Card>
</CardGroup>


# Categories
Source: https://docs.open.cx/help-center/categories

Group articles into categories your customers browse and your team can bulk-edit.

**Categories** group related articles into the top-level sections your customers browse on the public Help Center. Every article belongs to exactly one category.

<Tip>
  Create a category from [**Help Center**](https://platform.open.cx/help-center) — open your Help Center and click **New topic** in the sidebar. The editor calls categories **topics**, and a category inside another one a **subtopic**.
</Tip>

## Categories vs. articles

Categories are lightweight — they exist only to organize articles.

| | Category | Article |
| - | - | - |
| **Purpose** | Navigation group | The content customers read |
| **Editable?** | Yes — edits save instantly | Yes — edits create a new draft, publish when ready |
| **Versioned?** | No — changes apply immediately | Yes — every publish writes a version |
| **Translated?** | Name and description translate automatically when a new language is enabled | Full body translates automatically; per-language publish state |
| **Deletable?** | Yes — choose where its articles and subcategories go, or delete them with it | Yes — with **Undo** |

## Edit a category

Open the category's **⋯** menu in the sidebar and choose **Edit** to change its name, icon and description. Changes are live immediately — no draft, no publish step.

What you edit is the language the sidebar is showing:

* **In the primary language**, the other languages are re-translated from the new name and description in the background.
* **In any other language**, only that translation changes. It is kept as you wrote it from then on, even when the primary name changes later. **Re-translate from source** in the same menu writes it again from the primary language.

## Reorder

Drag categories in the sidebar to reorder. The public Help Center navigation reflects your order; search and the AI are not affected. You can also drag a category into another one to nest it, or drag articles between categories.

By default a move made in one language is made in every language: the category or article lands at the end of its new place in the others, and stays where it is in any language where it was already there. Reordering within the same place only changes the language you are viewing. Turn off **Moves apply to every language** in **Settings → General** to arrange each language on its own; the API and the Companion can also choose per move with `scope`.

## Delete

Deleting a category that still holds content asks what to do with it: **move it to another category** (the default — articles keep their addresses and the AI keeps training on them) or **delete everything in it too**. Either way the confirmation toast offers **Undo**, which brings the category back with whatever was deleted along with it.

## Good to know

<AccordionGroup>
  <Accordion title="One category per article" icon="file-lines">
    Articles belong to exactly one category. If the same content fits two places, link to it from the second category's article list or write a short cross-reference article.
  </Accordion>

  <Accordion title="Translations are automatic" icon="language">
    Category names and descriptions translate automatically when a new language is enabled. Manual overrides work the same way as articles — see [Translations](/help-center/translations).
  </Accordion>

  <Accordion title="No draft state" icon="bolt">
    Unlike articles, a category's name and description update the public site instantly. Pick the name you want to ship — there's no preview step.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Articles" icon="file-lines" href="/help-center/articles">
    Write and publish the content that goes inside categories.
  </Card>

  <Card title="Translations" icon="language" href="/help-center/translations">
    Multi-language for category names, descriptions, and articles.
  </Card>

  <Card title="Help Center overview" icon="book-open" href="/help-center/overview">
    Everything the Help Center does.
  </Card>
</CardGroup>


# Help Center
Source: https://docs.open.cx/help-center/overview

Author a customer-facing knowledge base inside OpenCX — articles train the AI and ship to your public help site at the same time.

The **Help Center** is a customer-facing knowledge base you author directly inside OpenCX. Articles ship to your public help site **and** sync into the AI's training index at the same time — one piece of content, two surfaces, no duplication.

<Tip>
  Open [**Help Center**](https://platform.open.cx/help-center) in your OpenCX dashboard to create a help center or jump into an existing one.
</Tip>

## What it does

<AccordionGroup>
  <Accordion title="One public site per organization" icon="globe">
    Each OpenCX org hosts one Help Center. Customers browse articles organized by **Categories**; articles are written in Markdown with a rich-text editor. You can point a custom domain at the site and customize colors and logo.
  </Accordion>

  <Accordion title="Every published article trains the AI" icon="brain">
    Publishing an article syncs it into the AI's training index. The AI retrieves from Help Center articles at answer time and cites them by title in replies. There's no separate "sync" step — publish is the trigger.
  </Accordion>

  <Accordion title="Multi-language with protected manual edits" icon="language">
    Set a primary language at creation. Enable other languages and the AI translates existing and new content automatically. Edit any translation by hand and it's flagged — future auto-translations will never overwrite it. See [Translations](/help-center/translations).
  </Accordion>
</AccordionGroup>

## Publish your first article

<Steps>
  <Step title="Create a Help Center">
    Open [**Help Center**](https://platform.open.cx/help-center) and click **Create**. Enter a **Name** (required) and optional description, then pick the **Primary language** and any additional languages you want auto-translated. You can change the look and domain later in settings.
  </Step>

  <Step title="Add a category">
    Categories group articles for navigation. Open your Help Center in the dashboard, click **+ New category** in the sidebar, and name it (for example, "Getting started", "Billing", "Troubleshooting").
  </Step>

  <Step title="Write an article">
    Click **+ New article** inside a category. Give it a title, then write the body in the visual editor (or toggle to Markdown with the source-mode button). The editor shows what the reader will see.
  </Step>

  <Step title="Publish">
    Click **Publish**. The article goes live on your public Help Center **and** syncs into the AI's training index in the same action. Drafts are never exposed to customers or the AI.
  </Step>
</Steps>

## Good to know

<AccordionGroup>
  <Accordion title="Set a custom domain and branding" icon="palette">
    In [**Help Center → Settings → Domain**](https://platform.open.cx/help-center) add a CNAME for your custom domain. Logo, primary color, and favicon live under **Settings → Customization**. The public site uses these automatically once verified.
  </Accordion>

  <Accordion title="One Help Center per organization" icon="building">
    If you need separate Help Centers (different brands, different products), create separate OpenCX orgs. Flag it with support if that's a blocker.
  </Accordion>

  <Accordion title="Generate articles from resolved sessions" icon="wand-magic-sparkles">
    After resolving a conversation in the [inbox](https://platform.open.cx/inbox), click **Generate Help Center article** on the session. OpenCX drafts a structured article from the conversation; it lands as a draft for you to review and publish. See [Articles](/help-center/articles).
  </Accordion>

  <Accordion title="Drafts stay private on every axis" icon="eye-slash">
    A draft article is not on the public site, not in the AI's training index, and not visible to customers via any channel. Publish is the one switch that flips all of that on.
  </Accordion>

  <Accordion title="Search understands questions" icon="magnifying-glass">
    Readers can type a question in their own words, like "how do I get my money back?", and press Enter: results match what the question means, not only its exact words, with articles whose title matches the search shown first. Suggestions while typing match titles and article text. Search covers only articles published in the reader's language.
  </Accordion>

  <Accordion title="See what the AI knows from your articles" icon="brain">
    Published articles appear under **Help Center** in the knowledge base of [**AI Instructions**](https://platform.open.cx/ai-instructions), one folder per help center. They're read-only there: edit, unpublish, or delete them in the Help Center editor and the knowledge base follows.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Articles" icon="file-lines" href="/help-center/articles">
    Write, version, and publish articles. AI-generate from resolved sessions.
  </Card>

  <Card title="Categories" icon="folder-tree" href="/help-center/categories">
    Organize articles into browsable groups.
  </Card>

  <Card title="Translations" icon="language" href="/help-center/translations">
    Multi-language, glossary, and manual-edit protection.
  </Card>
</CardGroup>


# Translations
Source: https://docs.open.cx/help-center/translations

Translate your Help Center into every language you support with AI — manual edits are protected from re-translation.

OpenCX translates Help Center articles, category names, and descriptions automatically into every language you enable. Manual edits are tracked so the AI never overwrites your polish.

<Warning>
  The **primary language** is fixed at the moment you create the Help Center and can't be changed later. Pick the language most of your authors write in — everything else translates from it.
</Warning>

## Set up languages

<Steps>
  <Step title="Open Languages settings">
    Go to [**Help Center → Settings → Languages**](https://platform.open.cx/help-center). The primary language is shown at the top, read-only.
  </Step>

  <Step title="Enable additional languages">
    Toggle on each language you want translated. Translation jobs queue immediately for all existing articles and categories.
  </Step>

  <Step title="Wait for translations to finish">
    Jobs run in the background. Article rows show per-language status (Not started, In progress, Translated, Manual). First batch can take minutes to hours depending on how many articles you have.
  </Step>
</Steps>

## When translations run

**Automatic translation** in [**Help Center → Settings → Languages**](https://platform.open.cx/help-center) decides when an article written in the primary language is translated into the others:

| Setting | What happens |
| - | - |
| **When an article is published** | The default. Translations are produced from the version readers see. Nothing translates while you draft. |
| **Never** | Nothing translates automatically — you write every translation yourself. |

Whatever the setting, these also trigger translation:

* **New language enabled** — jobs queue for every existing article and category.
* **Category created or renamed** — the name and description translate right away.
* **Manual re-translate** — click **Re-translate from source** on any translation to force a fresh run.

Translations regenerate for every language except those marked manual.

## Translation glossary

The glossary keeps terminology consistent across languages. Every translation prompt includes your glossary, so product names, acronyms, and branded phrases come out the way you intend.

<Steps>
  <Step title="Open Translations settings">
    Go to [**Help Center → Settings → Translations**](https://platform.open.cx/help-center).
  </Step>

  <Step title="Add a glossary entry">
    Click **+ Add term**.

    | Field | What to write |
    | - | - |
    | **Term** | The word or phrase in your primary language. Max 200 characters. |
    | **Translation note** | A short instruction for the translator — e.g. "Keep as 'Dashboard' in every language" or "Translate literally, don't localize". Max 1000 characters. |
  </Step>

  <Step title="Save">
    Glossary entries apply on the next translation job. To backfill, run **Re-translate from source** on the articles you care about.
  </Step>
</Steps>

## Protect manual translations

When you edit a translated article or category by hand, OpenCX marks it as **Manual**. Auto-translation will never overwrite a manual entry — even on republish or source change.

* **Force a re-translate** — use **Re-translate from source** (the **⋮** menu while viewing the translation) to overwrite a manual translation explicitly. The hand-written text stays in the version history, and the language follows the source again afterwards. The confirmation dialog calls out the manual flag so you don't lose edits by accident.

<Note>
  Manual translations don't block source updates. You can keep editing the English article; only the translation you marked manual stays frozen.
</Note>

## Good to know

<AccordionGroup>
  <Accordion title="Per-language publish state" icon="toggle-on">
    Each translation publishes independently. You can ship the English update today and wait on the French translation tomorrow — neither blocks the other.
  </Accordion>

  <Accordion title="Translated articles also train the AI" icon="brain">
    The AI retrieves content in the language the conversation is happening in. Publishing the French translation adds that language to the training index for French conversations. An article written in a language other than your Help Center's primary one trains the AI from the moment it is published, in the language it was written in; once its primary-language translation is live, the AI uses that.
  </Accordion>

  <Accordion title="Category names translate too" icon="folder-tree">
    Enable a new language and category names and descriptions translate alongside articles. Glossary rules apply here the same way.
  </Accordion>

  <Accordion title="Opening a language that is still translating" icon="hourglass-half">
    The sidebar and the language menu show **Translating…** while a translation is being written. You can open it anyway: a banner says so, and the text appears in place when it is ready. Anything you type in the meantime is kept as your draft.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Articles" icon="file-lines" href="/help-center/articles">
    Write the primary-language content translations derive from.
  </Card>

  <Card title="Categories" icon="folder-tree" href="/help-center/categories">
    Categories translate automatically alongside articles.
  </Card>

  <Card title="Help Center overview" icon="book-open" href="/help-center/overview">
    Everything the Help Center does.
  </Card>
</CardGroup>


# How OpenCX Works
Source: https://docs.open.cx/how-opencx-works

The mental model behind OpenCX — channels ingest, AI answers from your knowledge, Autopilot gates replies, Actions do real work, Handoff routes the rest.

Every OpenCX agent is the same five pieces wired together. Once you understand the shape, every channel, feature, and integration fits the same mental model.

## The flow

```mermaid theme={"dark"}
flowchart LR
  A[Customer message] --> B[Channel]
  B --> C{Autopilot}
  C -->|on| D[AI agent]
  C -->|off| F[Human team]
  D --> E[Knowledge + Actions]
  E --> G[Reply]
  D -.handoff.-> F
```

1. **A message arrives** on one of your channels — widget, phone, WhatsApp, email, or SMS.
2. **Autopilot decides** whether the AI replies or the message goes straight to your team.
3. **If the AI replies**, it reads from your Knowledge, optionally calls Actions (your APIs), and sends a reply back on the same channel.
4. **Anything the AI cannot confidently handle** (low confidence, prohibited topic, frustrated user) hands off to a human.

## The five pieces

<AccordionGroup>
  <Accordion title="Channels — where messages come from" icon="satellite-dish">
    Each channel (widget, phone, email, SMS, WhatsApp) captures messages from your customers and normalizes them into **sessions**. A session is the OpenCX-wide unit of a single conversation regardless of channel. See [Build Agents](/build-agents/get-started).
  </Accordion>

  <Accordion title="Knowledge — what the AI reads from" icon="book">
    The AI answers from two sources: **Help Center content** (articles you write) and **Knowledge Sources** (connected systems like Zendesk, Notion, Confluence, your website). It also uses **Training Scenarios** you write by hand for exact answers. See [Agent Training](/knowledge/introduction).
  </Accordion>

  <Accordion title="Autopilot — when the AI replies" icon="sliders">
    Autopilot is the on/off switch per channel. When on, the AI responds automatically. When off, every message routes to your team's inbox. You can also gate autopilot by **topic** — reply to billing questions, hand off login issues. See [Autopilot topics](/handoff/topics).
  </Accordion>

  <Accordion title="Actions — what the AI can do" icon="bolt">
    Actions let the AI call your APIs at conversation time — look up an order, cancel a subscription, update a field. You define them with an OpenAPI-style spec and the AI picks the right one based on the customer's intent. See [AI Actions](/actions/introduction).
  </Accordion>

  <Accordion title="Handoff — how humans take over" icon="user-group">
    When the AI hits its limits, the session hands off to a human. OpenCX syncs the full conversation to your helpdesk (Zendesk, Hubspot, Intercom, etc.) so your team sees the context. See [Handoff](/handoff/introduction).
  </Accordion>
</AccordionGroup>

## Why this shape

Most customer support tools either automate everything (and answer the easy questions but fail on the hard ones) or route everything to humans (and burn payroll on FAQs).

OpenCX separates the decision from the answer. **Autopilot decides**, **Knowledge + Actions answer**, **Handoff catches the rest**. You tune any piece without rebuilding the others — swap the helpdesk without retraining, add a channel without redoing autopilot rules.

***

## Related Documentation

<CardGroup>
  <Card title="Core Concepts" icon="book" href="/core-concepts">
    The vocabulary: session, ticket, autopilot, handoff, action, insight.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Skip the theory — stand up your first agent in 10 minutes.
  </Card>

  <Card title="Build Agents" icon="robot" href="/build-agents/get-started">
    Pick a channel and go live.
  </Card>

  <Card title="AI Safety" icon="shield" href="/safety/introduction">
    What the AI won't do — PII redaction, prohibited topics, inspect mode.
  </Card>
</CardGroup>


# Session attribute dropdowns
Source: https://docs.open.cx/inbox/dropdown-attributes

Use an existing Structured Fields enum as a searchable dropdown so agents can correct contact reasons and other session attributes in the Inbox.

Use an enum from [Structured Fields](/ticketing/structured-fields) when agents need to correct a session attribute by choosing from a predefined list. A workflow can write a contact reason to `__classification`, and an agent can select another value in **Session attributes** in the Inbox.

The enum owns the choices. There is no separate choice list or label/value mapping for the session attribute. You can link the same enum to different attributes. Contact attributes are not supported.

## Link an enum to a session attribute

You need permission to view settings and Structured Fields to open the page, and permission to edit Structured Fields to manage links. Agents need session editing permission to select a value.

1. Open **Settings → Structured Fields**. Create an **Enum** and its choices, or expand an existing enum.
2. Choose **Link a session attribute** below its choices.
3. Search for the exact attribute key, such as `__classification` or `contact_reason`. Each key appears once. You can also enter a new key.
4. Enable **Show when empty** if agents should see the dropdown before the attribute has a value. This is off by default. **Allow agent editing** is on by default.
5. Choose **Link attribute**.

To reuse the same enum for another attribute, choose **Link another session attribute**. An attribute can be linked to only one enum.

Manage the choices in the enum itself. Changes to its choices are reflected in linked dropdowns. Nested enums offer their leaf choices. Each enum supports up to **1,000 choices**.

The attribute picker offers one entry per key. New keys use Session data; keys found only in Agent-added data use that source for sessions where the key is missing. If the key already exists on a session, the dropdown updates it in place.

A selection writes the existing choice's API value to the bound attribute. Check that your enum's values match what the classifier or workflow expects. Linking an enum does not rewrite session values or change the enum's own per-session values and conditional rules.

## Correct a session value

1. Open a session and find the linked attribute under **Session attributes**.
2. Click its value or the chevrons and search for a choice. Search covers all choices, including large lists.
3. Click a result, or use the arrow keys and Enter. The change saves immediately.

If multiple choices have the same displayed path, their API values appear in parentheses so you can distinguish them. Unique choice names stay unchanged.

Opening the dropdown or typing in search does not change the session. Escape closes it without selecting. Other session attributes keep their normal appearance. Existing pins, hidden attributes, and **Show more** still apply.

If an enum is linked while you have an unsaved edit, your draft stays visible above the dropdown. Select a choice to save a value, or choose **Discard draft**. Selecting a value preserves pending edits to other attributes.

The dropdown updates the existing attribute in place. For a key linked to an active enum, if an older session contains it in both Session data and Agent-added data, **Session data takes precedence** and only one row is shown. Saving a dropdown selection removes that key's duplicate from Agent-added data in the same save, while preserving other keys. Ordinary session writes do not clean up duplicates. A later workflow or integration can create a duplicate again; the sidebar still shows one row, and the next dropdown save removes the duplicate. This duplicate handling applies only to attributes linked through this feature; unlinked attributes keep their existing behavior.

Only the linked attribute changes. Its existing workflow and integration behavior still applies. **Later updates win**: a workflow, classifier, or integration can replace an agent's selection, including with a value outside the enum.

## Existing values and troubleshooting

* **Not in available choices:** An older or externally supplied value stays visible until a new value is saved. Removing a choice does not erase it from sessions.
* **The dropdown is missing:** Check the linked key, hidden attribute settings, and **Show more**. Enable **Show when empty** if the attribute has not been set. Removed enums are not offered.
* **The dropdown is disabled:** Check **Allow agent editing** and your session editing permissions. It also disables briefly while saving.
* **A save fails:** Check the current value and retry. A downstream update can fail after the value is written, so the sidebar refreshes to show the current stored value.
* **Attribute keys must be unique:** Rename or remove duplicate unsaved rows before using the sidebar's **Save** button. Removing an unsaved row does not delete an existing attribute.
* **Remove a link:** Expand its enum in **Structured Fields** and choose **Unlink** beside the attribute, then confirm with **Unlink attribute**. Cancel keeps the link. Session values remain, and the attribute returns to its normal display and editing behavior.


# Inbox
Source: https://docs.open.cx/inbox/intro

Manage customer sessions across channels in Inbox. Answer AI help requests, reply without taking over, and find past sessions by tag.

<Frame>
  <img alt="OpenCX Inbox with conversations from every channel in one place" />
</Frame>

**(*Everything is in a single place, no matter what channel you are using—email, chat, phone,
etc.*)**

The Inbox is a centralized place to view, manage, and take action on your customer support conversations across all your channels (email, chat, phone, etc.).

* You will be able to see all your customer support conversations in one place.
* You can take action on your conversations from the Inbox (reply, change status, add notes, share, etc.).

**Types of Inboxes:**

* **Assigned to Me** - Any conversation you have with a customer assigned to you.
* **Assigned to Copilot** - Any conversation that is being handled by the AI.
* **Unassigned** - Any conversation that is not assigned to you or the AI.
* **Everything** - All conversations.

Hover over the last-message preview on a session card to read its full text in a
tooltip without opening the session, just as you can with the session title.
For long messages, move your pointer into the tooltip and scroll to read the rest.

## See who is viewing a session

Small teammate avatars on the right of an Inbox session card mean someone else
is viewing that session. They appear to the left of the summary icon when one is
shown. Up to three avatars overlap in a stack; **+N** counts any additional
viewers. Hover over the indicator to see everyone's names; scroll inside the
tooltip when the list is long.
Your own avatar is excluded, and multiple tabs belonging to one teammate count once.

Viewing is separate from assignment and does not prevent you from opening or
replying to the session. Indicators refresh about every 10 seconds while your
Inbox tab is visible. After a browser closes unexpectedly, an indicator can take
about 40 seconds to disappear. An absent indicator is not a guarantee that nobody
else is working on the session.

## Answer an AI help request

With [Team in the loop](/handoff/settings#team-in-the-loop) enabled, the AI can mention you in an internal Inbox note when it needs help. The customer sees the AI's progress message, while the note and your thread reply stay private.

1. Open the session from the mention notification or find it with the **AI needs help** tag.
2. Open the help note's thread and reply with the answer or confirmation the AI needs.
3. The AI follows up with the customer in the same session. If another question joined the note thread, answer the latest request there.

You can also reply directly to the customer. That answers the open help request, and the AI resumes when the customer next writes.

### Reply without taking over

When Team in the loop applies to an AI-assigned session, typing and sending replies keep AI assigned, even if it has not asked for help. Before your first direct reply, a dialog offers:

* **Send reply** — send your message and keep AI available.
* **Take over and send** — assign the session to yourself, then send.
* **×** — close the dialog and keep the draft unsent.

The choice is acknowledged once per member and workspace in that browser. Later replies send without the dialog. To take over at any time, open the **AI** assignee menu in the session header and choose **Take over**.

### Review past requests

Filter by the **AI needs help** tag and include closed sessions to review past requests. Save those filters as a view to return to them later. The tag remains after an answer or takeover, so tagged sessions are a history of requests, not a list of unanswered ones.

## Send and resolve

To reply and resolve an open session in one action, write your reply, open the arrow
beside **Send**, and select **Send and resolve**. You can also press **⌘⇧Enter** on
Mac or **Ctrl⇧Enter** on Windows and Linux. The main **Send** button and your existing
send shortcut continue to send without resolving.

If your workspace requires Structured Fields before closing, complete the form first.
The form follows the session team's requirements and includes values already recorded.
Choose **Send and resolve** to continue, or **Cancel** to keep your draft unsent.

The session resolves after the reply succeeds. If the reply fails, the session stays
open and your draft remains. If the reply succeeds but resolution fails, use
**Resolve session** in the same menu to retry without sending the reply again.
After successful resolution, your preference to open the next assigned session still applies.

This action requires permission to update sessions. It is available for replies to
open sessions; internal notes and WhatsApp template sending keep their existing behavior.

### Send and set a custom status

Workspace admins can add custom statuses to the same menu under **Settings → Workspace →
Send and set status**. Each enabled status appears as **Send and \[status]**, in the order
it was added. Choosing one sends your reply and then applies that status. A status that
closes the session follows the same rules as **Send and resolve**: the Structured Fields
form, the retry option (**Set \[status]**) if only the status change fails, and your
open-next-session preference. A status that keeps the session open skips those steps.
Statuses limited to certain teams only appear for agents in those teams.

## Change an email session's primary contact

In a native OpenCX email session, select the recipient beside **To** above the reply
composer. Search for an existing contact by name or email, or enter a new email
address and select **Use**. Contact search requires permission to read contacts;
you can still enter an email address without it. Review **Cc**, then select **Send**.
Sending transfers the existing session to that person as its primary contact.
Editing the draft or opening Preview does not transfer the session.

If the new contact has no name yet, their email address identifies them in the
inbox. When they reply with a sender name, that name appears on their contact.

* The new primary contact receives your reply and earlier customer-visible history.
  Earlier file attachments are available as download links beside their original
  messages in that history. Internal notes and unsent AI suggestions are excluded.
* Existing Cc recipients remain editable. The previous primary contact is not
  automatically added to Cc and receives no new email unless included.
* The timeline records who changed the primary contact, the previous and new
  contacts, and when the change happened. Earlier messages keep their original authors.
* Replies from either the new contact or an earlier participant can join the same
  session. An earlier participant's reply does not change the primary contact back.
* Existing AI and human-assignment rules continue. Changing To is a human action;
  it does not introduce an additional automation mode.

If delivery fails after the transfer is saved, the new primary contact remains.
The email shows its delivery status; use **Retry email** to retry that message.
If sending is interrupted, OpenCX resumes the saved attempt once the previous send
is no longer active. Emails already accepted for delivery finish their session
updates without being sent again. Older unconfirmed sends require delivery review.
Reopening a saved email draft keeps its files and quoted-message reference, so
retrying an unchanged draft continues the original send. File removals and changes
to the quoted message are saved separately, so reopening an edited draft keeps those edits.
Automatic recovery keeps the current assignment if the original author has left the organization.
Retrying preserves its original author and recipients without replacing an existing
human assignee or reopening the session. If the requested takeover from AI did not
complete, retrying finishes it as the teammate who selects **Retry email**. The
session is marked read for that teammate. Redacting email content removes saved delivery
copies and disables existing retries in that session and sessions containing
linked copies of the redacted messages.
If another agent changes the contact while you are drafting, review To and Cc
before sending. **Send and resolve** resolves the session only after sending succeeds.

Changing To shares a session's customer-visible history. For a separate exchange
with a supplier or colleague, use a linked sub-session instead. To editing supports
one recipient plus Cc and is available only for native OpenCX email inboxes, not
integration-backed sessions or campaign mailboxes. Sending requires permission to
write sessions.

## Set session priority

Priority is off by default. For native OpenCX ticketing, a workspace admin can open **Settings → Workspace → Session priority** and turn on **Enable session priority**. Changing this setting requires permission to edit workspace settings. Priority is not connected to external ticketing integrations.

Once enabled, changing a session's priority requires **Sessions** write permission.

1. Open a session and select **Set priority** beneath its title, or select its current priority badge.
2. Choose a standard or custom priority from your workspace’s list. Choose **None** to clear the priority.
3. Check the internal timeline to see who changed it. Priority also appears on session cards.

Sessions start with **None**. Priority stays set when a session closes, reopens, or moves to another team. It does not change the assignee, send a customer message, or set an SLA target, and it does not increase automatically as the customer waits.

Use the **Priority** filter to find sessions at a particular level, or select **Priority** in the sort menu. Descending order follows your workspace’s configured order, highest first and **None** last. Ascending reverses that order. Sessions at the same level are ordered by their last activity. Changing the display order does not change automatic assignment.

Turning the workspace setting off hides the priority controls, filters, sorting option, and new workflow action. Teams return to their default waiting order, and saved priority filters and sorts are ignored. Saved priorities, team assignment settings, and timeline history are kept and become available again when re-enabled.

For agents who serve multiple teams, workspace admins can enable **Prioritize across Priority-first teams** in the same Workspace settings section. It compares eligible waiting sessions across those teams while preserving each team’s assignment delay. It is off by default; see [cross-team priority assignment](/teams#prioritize-across-teams).

### Create and order custom priorities

Open **Settings → Workspace → Session priority** with permission to edit workspace settings. Enable session priority to manage the list.

1. Select **Add priority**, enter a unique name such as **VIP** or **Security**, choose a **Priority color**, and select **Save**. The color styles the whole priority pill—flag, text, border, and tinted background—on session cards and in the session header.
2. Once an active custom priority exists, the **Priority order** list appears. Drag the priority to its place, highest first. You can also focus its move handle, press Space, use the arrow keys, and press Space again.
3. Use the pencil to edit a custom priority’s name or color. Select **Reset** to return to the default appearance. The standard names stay fixed, and **None** always remains lowest.

New priorities start just above **None**. Standard and custom levels can be reordered together—for example, **Security → VIP → Urgent → High → Medium → Low → None**. The order is shared by the Inbox, workflow pickers, and teams using priority-based assignment. Changes apply to waiting sessions on subsequent assignment passes and do not move existing assignees.

To remove a custom priority, select its trash icon and choose a replacement. Existing sessions, saved filters, and workflow actions and conditions use the replacement automatically. Renaming or removing a priority does not rewrite names in historical timeline events. Standard priorities cannot be removed. Removing the last active custom priority hides the ordering list; **Add priority** remains available, and the saved order is kept.

### Set priority in a workflow

Add **Set session priority**, select the session number, and choose a standard or custom level. Use **Session priority** in a workflow condition to branch on levels such as **VIP**. Place this action before the team assignment step when priority should affect that assignment. Changing priority alone does not start a **Session Updated** workflow. While the workspace setting is off, existing priority actions are skipped and the rest of the workflow continues. Conditions can still read saved priorities. Existing actions and conditions follow the chosen replacement if a custom priority is removed.

Automatic assignment uses priority when the team selects **Priority first** or **SLA first**. See [team assignment order](/teams#choose-session-assignment-order) for how priority, SLA deadlines, and waiting time interact.

## Snooze a session

For native OpenCX ticketing, enable **Settings → Workspace → Session snoozing →
Enable session snoozing**. It starts off. Changing the setting requires workspace
settings permission; snoozing from the inbox requires permission to update sessions.

Select **Snooze** from an open session's status menu. Choose **1 hour**, **3 hours**,
**Tomorrow at 9 AM**, or a custom date and time. Times use your local timezone.
Only human-assigned or unassigned sessions can be snoozed; sessions with an active
call cannot be snoozed.

Snoozed sessions leave working views and free agent capacity. They remain
unresolved, keep their assignee and custom status, and stay accessible through
**All sessions**, search, direct links, and the **Snoozed** view. The Snoozed view
lists the earliest wake-up times first. When sorting mixed views by Snooze time,
sessions without a scheduled return appear last. Use the **Snooze** filter to include or
exclude snoozed sessions in a saved view.

A session returns when its snooze time arrives, a customer replies, an active SLA
breaches, a new call starts on the session, or an agent selects **Open** to unsnooze it. A wake-up is scheduled for the chosen deadline; it does not wait for the periodic
recovery check. Select **Snooze** again
to adjust the deadline. Agents' replies, notes, and human reassignment do not end
Snooze. Customers do not see a snoozed status.

SLAs continue under their existing rules. Inactivity follow-ups wait while the
session is snoozed and start a fresh inactivity period after it wakes, where
applicable. Workflows already running are not suspended. The session returns to
its current assignee even if they are away or at capacity; unassigned sessions
return to normal team routing.

Closing a session or assigning it to AI cancels Snooze. Disabling session snoozing
returns existing snoozed sessions to active work on the next processing cycle.
Snooze is available in the inbox and through the **Snooze Session** workflow action.
This feature does not add external integration synchronization or bulk actions.

### Snooze from a workflow

With **Enable session snoozing** on, add **Snooze Session** to a workflow. Set
**Session Number** (for example, the triggering session's number) and **Snooze
Duration** to a preset (5, 15, or 30 minutes; 1 or 3 hours; or 1 day), or choose
**Custom duration** and enter at least `1` minute. The duration starts when the step executes.
The workflow continues to its next step immediately; Snooze does not wait for the
session to wake.

The same eligibility and wake-up rules apply as inbox Snooze. The timeline records
which workflow run snoozed the session. If the workspace setting is disabled
before execution, the step fails without changing the session.

### Use Snooze in workflow conditions

In a **Session Updated** workflow, watch **Status** and compare
`{{trigger.ticket.ticketStatus}}` with `snooze` in an If/Else condition. Entering
Snooze and returning to Open fire status updates. Changing only the wake-up time
does not fire another status update. **Group by → Status** also places these
sessions in their own **Snooze** group.

## Correct session attributes

Use [session attribute dropdowns](/inbox/dropdown-attributes) to search a predefined list and correct a contact reason or another session attribute. Link an enum under **Settings → Structured Fields**, then select a value directly in the session sidebar.

## Group sessions

In **Filters → Group by**, choose **Tags**, **Contact attribute**, or **Session
attribute** alongside the existing channel, assignee, status, AI status, language,
and support team options. For an attribute, select a suggested key or type its
exact name. The list stays ungrouped until you choose a key. You need permission
to edit personal or shared views to change grouping. Save the view to keep its
grouping and attribute key.

* **Tags:** A session appears under each of its tags. Sessions with no tags appear
  under **Untagged**, so a tagged session can appear more than once in the list.
* **Contact attribute:** Uses the linked contact's verified attributes.
* **Session attribute:** Uses the session's attributes, including editable
  attributes when the same key is absent from its stored attributes. If a key
  exists in both, the stored value takes precedence, even when empty.

Attribute groups support text, numbers, and booleans. Missing, null, and empty
values appear under **Not set**, always at the bottom. Objects and arrays appear
in a separate **Object / array** group. Hidden attributes remain hidden and cannot
be used to recover their values through grouping.

Grouping covers **loaded sessions only**. Scrolling loads more sessions into the
groups; the API still returns individual sessions. Other groups appear in the
order their first session occurs, and sessions keep their sort order within each
group. Choosing **None** restores the flat list.

### Collapse session groups

Choose a grouping in **Filters → Group by**. Each group starts expanded. Click its
header or chevron to collapse its sessions and bring the next group into view;
click again to expand it. You can also focus a group header and press **Enter** or
**Space**. This works with every grouping option.

Collapsing a group only changes the list display. It does not change the sessions
or the view's filters. Groups cover loaded sessions and update as more sessions
load. Collapsed groups stay collapsed while you browse the inbox; reloading the
page expands them again.

## Personalization

### Views sidebar

Enable **Show views in sidebar** under **Settings → Personalization → Inbox** to
keep views beside the session list. Search views by name, select a view to open its
sessions, and see counts alongside each view. Contact and session attributes remain
on the far right with their existing resize and hide controls.

Use **Create view** (+) to build a view, the row's **Actions** menu to edit or delete
it, and **Manage views** for saving filters, saving a new view, or reordering personal
views. Available actions depend on your permissions. Shared ordering and your
workspace's visibility settings still apply.

Workspace admins can enable **Show views in sidebar by default** under
**Settings → Workspace → Inbox views**. Changing this setting requires permission
to edit workspace settings. It starts off and applies to teammates without a saved
personal sidebar choice.

An existing personal on/off choice is preserved. Your personal choice follows your
account across browsers and workspaces and does not affect teammates. To follow
the active workspace's default again, select **Use workspace default** beside the
sidebar switch in Personalization. Changing another personal preference does not
stop you from following the workspace default.

Smaller windows automatically use the dropdown;
widening the window restores the sidebar unless you have hidden it. Press **V** to
search views in either layout.

Use **Hide views** beside the active view name to give the session more space. The
same button becomes **Show views** so you can bring the sidebar back. Your selected
view, open session, and unsent reply stay in place. The collapsed state is remembered
in this browser without changing your Personalization setting.

### Composer toolbar

Open **Settings → Personalization** and enable **Pin composer toolbar** under **Inbox**
to keep formatting and AI Copilot controls above the session composer. In email sessions,
the toolbar sits above Cc. It also applies when writing internal comments.

This setting is off by default: the toolbar appears when you select text. Your choice
is saved for your account across browsers and does not affect teammates. It applies to
session replies and comments, not the New Session dialog. Available formatting and
delivery behavior remain the same for each channel.

Enable **Macros button** under **Inbox** to add a macros button to the session composer
toolbar. It opens a searchable list of your macros with a preview of the
highlighted one; choosing a macro inserts it where your cursor is. While the button is on,
macros no longer appear in the **/** menu.

This setting is off by default: macros are inserted from the **/** menu. Your choice is
saved for your account across browsers and does not affect teammates. It applies to
session replies and comments, not the New Session dialog.

### Translate messages in your view

Open the session's **More options → Translation → Target language** menu to choose
which language you read. Under **Display style**, choose **Show translation beneath
original content** or **Only show translation**. These settings affect your dashboard
view; they do not rewrite stored messages or change outbound translation settings.

Translated message bodies preserve paragraphs, line breaks, emphasis, links, lists,
and nested quotations. In email sessions, quoted history stays behind **•••** in
both the message view and the email experience. Expand it to read the history;
its original text remains visible while its translation loads. A failed history
translation leaves the translated message body visible and labels the history as
original. If only the history is translated, only that section is labeled as a
translation. If translation is unavailable, the original content remains readable.

In the email experience, **Only show translation** displays one translated email
once it is ready, retaining its inline images, layout, and quoted-history control.
**Show translation beneath original content** displays both versions. Attachments
remain available below the email; inline images are not repeated as attachments.
The original stays visible while translation is loading or unavailable. Text inside
image files is not translated.

### Macro options

A macro can carry up to 3 options the customer taps instead of typing, such as **Yes** and
**No** on a consent question. Add them in **Settings → Macros** when you create or edit an
org-wide macro, or set them through the API (`options` on `POST /macros` and
`PATCH /macros/{id}`) or the Companion. Each label is up to 20
characters. Personal macros can't have options; a personal version of an org-wide macro sends
the org-wide macro's options.

Each option does one of two things when tapped:

* **Send as reply** — the label reaches the session as the customer's message and is
  handled like anything they type.
* **Trigger workflow** — the tap runs your **Macro Option Clicked** workflows for that macro
  and the AI doesn't reply. Branch on **Option ID** or **Option Label** in the workflow.
  This works whoever owns the session. If no active workflow listens for the macro, the tap
  is handled like a message the customer typed.

Only the first tap on the newest message with options counts. A second tap, a tap on an
older message's options, or a tap on a closed session arrives as a normal message and runs
nothing. The message in the
session timeline shows the options that were sent and marks the one the customer picked.

The **/** menu, the macro picker and the composer show a macro's options before you send it;
remove them from the composer to send the message without options.
Options are sent as buttons on the web widget, WhatsApp, Messenger and Instagram, and delivered
to your own client on API sessions (see [Send a message](/api-reference/chat-sessions/send#option-taps)).
A website running an older widget version shows the message without the buttons; the customer
can still type their answer. On other channels, including sessions linked to HubSpot or
Intercom conversations, only the message is sent, and the inbox tells you so when you insert
the macro.
The first message of a new session is always sent without options. On WhatsApp, a message with
options is limited to 1,024 characters.

### FAQ

<AccordionGroup>
  <Accordion title="Does the inbox refresh when I switch tabs?">
    Periodic refreshes of the session list and selected session details pause while the browser
    tab is hidden. They refresh when you return to the tab. Live session updates can still arrive
    while the tab is in the background.
  </Accordion>

  <Accordion title="Where is my session after I reply?">
    Check the assignee in the session header and your current Inbox filters. When
    Team in the loop applies, replying keeps the session assigned to AI. If you
    took over, find it among sessions assigned to you. For other sessions, the
    existing assignment behavior still applies.
  </Accordion>

  <Accordion title="What happens if I reply to a phone conversation using text?">
    If you reply to a phone conversation using text, Open will send this text message to the customer's phone number.
  </Accordion>
</AccordionGroup>

## Available APIs

Open provides top-of-the-line APIs for developers to build on top of our platform, including inbox APIs.

<CardGroup>
  <Card title="Inbox" icon="inbox" href="/api-reference/chat-sessions/list">
    List and manage support requests and conversations from web, phone, and email channels in a
    single place.
  </Card>
</CardGroup>


# Aircall connect
Source: https://docs.open.cx/integrations/aircall/connect

Generate an Aircall API ID and token from the Aircall dashboard, store them as organization variables, and reference them from the Post Call Context workflow action.

OpenCX workflows authenticate to Aircall with an <Tooltip>API key</Tooltip> — an **API ID** and an **API token** used together as HTTP Basic auth. Store the pair as organization variables once, then reference them from every workflow node that touches Aircall.

## Generate credentials

<Steps>
  <Step title="Open the Aircall API keys page">
    Sign in to your Aircall dashboard as an admin, open the **Integrations & API** page, and select [**API Keys**](https://dashboard.aircall.io/view-api-keys) in the upper-right corner.
  </Step>

  <Step title="Create an API key">
    Click **Generate an API key**, give the key a recognizable name, and Aircall shows you two values: the **API ID** and the **API token**.

    <Warning>
      Anyone with the pair can read and write your Aircall data — calls, contacts, users. Treat it like a password. Copy both values before closing the popup: the **API token** is displayed only once at creation time and cannot be retrieved later.
    </Warning>
  </Step>

  <Step title="Store both somewhere safe">
    Drop both into your password manager or secret store, then add them as OpenCX organization variables (next section) so workflows can reference them.
  </Step>
</Steps>

## Store as organization variables

Instead of pasting the raw credentials into every workflow node, store them once as organization variables — values are **encrypted at rest** and decrypted per run:

<Steps>
  <Step title="Open the variables page">
    Go to **[Settings → Variables](https://platform.open.cx/settings)**.
  </Step>

  <Step title="Add two variables">
    Create `aircall_api_id` with the API ID as its value, and `aircall_api_token` with the API token.
  </Step>

  <Step title="Reference them from workflows">
    In any workflow node with Aircall credential inputs (e.g. [Post Call Context](/integrations/aircall/post-call-context-action)), set **Aircall API ID** to `{{variables.aircall_api_id}}` and **Aircall API Token** to `{{variables.aircall_api_token}}`.
  </Step>
</Steps>

<Info>
  Rotating the key becomes a one-place change: generate a new key in Aircall, update the two variable values, and every workflow referencing them picks up the new credentials on its next run — no workflow edits needed.
</Info>

<Note>
  Organization variables are shared with [AI action calls](/actions/authentication), where each key/value is sent as an HTTP header on outbound requests to your own action endpoints. Keep that in mind when naming and scoping the keys.
</Note>

## Verify the connection

Aircall exposes a ping endpoint that answers with `{"ping": "pong"}` when the credentials are valid. Aircall recommends sending the pair Base64-encoded in the `Authorization` header (not embedded in the URL):

```bash theme={"dark"}
curl https://api.aircall.io/v1/ping \
  -H "Authorization: Basic $(printf '%s' 'YOUR_API_ID:YOUR_API_TOKEN' | base64)"
```

A `403 Forbidden` response means the ID/token pair is wrong or was revoked — regenerate the key from the [API Keys page](https://dashboard.aircall.io/view-api-keys).

***

## Related Documentation

<CardGroup>
  <Card title="Post Call Context Action" icon="phone-forwarded" href="/integrations/aircall/post-call-context-action">
    Full reference for the workflow action.
  </Card>

  <Card title="Overview" icon="phone" href="/integrations/aircall/overview">
    What the Aircall integration does at a glance.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/aircall/troubleshooting">
    Credentials rejected, call not found, comment limits.
  </Card>

  <Card title="AI Phone agent configuration" icon="gear" href="/phone/agent-config">
    Set up the transfer destination that forwards to Aircall.
  </Card>
</CardGroup>


# Aircall overview
Source: https://docs.open.cx/integrations/aircall/overview

Hand calls from the OpenCX AI phone agent to your Aircall team with the full conversation context attached to the Aircall call.

OpenCX connects to Aircall through workflows. When the AI phone agent transfers a call to your Aircall line, a workflow finds that call in Aircall and attaches the conversation context — so the human agent picking up knows who is calling, why, and what the AI already covered.

## What you get

<AccordionGroup>
  <Accordion title="A live insight card during the call" icon="id-card">
    While the transferred call is ringing or ongoing, the receiving agent sees an <Tooltip>insight card</Tooltip> in their Aircall phone app: the transfer reason, caller sentiment, a session link — whatever your workflow puts on it.
  </Accordion>

  <Accordion title="A permanent note on the call record" icon="note-sticky">
    The same workflow can post a <Tooltip>call comment</Tooltip> with the AI conversation summary, so the context survives after the call ends and is visible in Aircall's dashboard and analytics.
  </Accordion>

  <Accordion title="Reliable call matching, no webhooks needed" icon="magnifying-glass">
    OpenCX finds the transferred call by searching Aircall for the caller's phone number, most recent call first. The search polls briefly to absorb Aircall's indexing lag and tries both `+`-prefixed and bare phone formats, so a format mismatch never loses the context.
  </Accordion>
</AccordionGroup>

## How it fits together

1. A caller talks to your OpenCX AI phone agent.
2. The AI decides to transfer and forwards the call to your Aircall number (a **Phone** transfer destination pointing at the Aircall line).
3. The transfer fires the **Voice Call Transferred** workflow trigger.
4. The workflow's **Post Call Context to Aircall** action searches Aircall for the caller's number, finds the just-arrived call, and posts the comment and/or insight card.

<Note>
  Aircall is a closed cloud PBX — calls reach it over the regular phone network, not via direct SIP. Point a **Phone**-type transfer destination at your Aircall number. The caller's number is preserved on the forwarded leg, which is exactly what the workflow searches by.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect" icon="plug" href="/integrations/aircall/connect">
    Generate an Aircall API ID and token.
  </Card>

  <Card title="Post Call Context Action" icon="phone-forwarded" href="/integrations/aircall/post-call-context-action">
    Configure the workflow action end to end.
  </Card>

  <Card title="AI Phone agent configuration" icon="gear" href="/phone/agent-config">
    Transfer destinations and workflow hooks on the phone agent.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/aircall/troubleshooting">
    Call not found, credential errors, comment limits.
  </Card>
</CardGroup>


# Post Call Context Action
Source: https://docs.open.cx/integrations/aircall/post-call-context-action

Find the transferred call in Aircall by caller number and attach a call comment and a live insight card from an OpenCX workflow.

The **Post Call Context to Aircall** action lives inside the workflow builder. After the AI transfers a call to your Aircall line, it finds that call in Aircall and posts a persistent call comment and/or a live insight card for the receiving agent.

<Tip>
  Pair it with the **Voice Call Transferred** trigger — it fires right after the AI completes a transfer and carries the caller, destination, and transfer reason in its payload.
</Tip>

## Configure the action

<Steps>
  <Step title="Create a workflow on the Voice Call Transferred trigger">
    In the flow builder, pick the **Voice Call Transferred** trigger. Optionally restrict it to the transfer destination that points at your Aircall number, so the workflow doesn't fire for transfers going elsewhere.
  </Step>

  <Step title="Drop the node into your workflow">
    Add a `Post Call Context to Aircall` node from the **Integrations** category.
  </Step>

  <Step title="Wire up your credentials">
    Fill **Aircall API ID** and **Aircall API Token** with the values from [Connect](/integrations/aircall/connect). Best stored once as organization variables and referenced as `{{variables.aircall_api_id}}` / `{{variables.aircall_api_token}}` — see [Store as organization variables](/integrations/aircall/connect#store-as-organization-variables).
  </Step>

  <Step title="Point it at the caller">
    Set **Caller Phone Number** to `{{trigger.ticket.contact.phone_number}}`. This is the number OpenCX searches for in Aircall to find the transferred call.
  </Step>

  <Step title="Generate a call summary (optional)">
    To include a full AI summary of the call in the note, add an **Ask AI About Ticket** step *before* this action. Point its **Ticket Number** at `{{trigger.ticket.ticketNumber}}`, prompt it to summarize the call for the receiving agent, and give it an expected output with a `summary` string field. Reference its output in the comment (e.g. `{{ask_summary.result.summary}}`).
  </Step>

  <Step title="Write the context">
    Fill **Call Comment** with the note you want on the call record (e.g. the AI summary and transfer reason), build a live card with **Insight Card Title** + **Insight Card Fields**, and/or set **Call Tags**. At least one of the three must be provided.
  </Step>
</Steps>

A typical configuration (with an Ask AI About Ticket step id'd `ask_summary` before this action):

* **Call Comment**:

  ```text theme={"dark"}
  Transferred from OpenCX AI agent.

  Reason: {{trigger.transfer_reason}}

  Summary:
  {{ask_summary.result.summary}}

  View session in OpenCX:
  https://platform.open.cx/inbox/?s={{trigger.ticket.ticketId}}&org={{organization.id}}
  ```

* **Insight Card Title**: `OpenCX AI Call Context`

* **Insight Card Fields**: `Reason → {{trigger.transfer_reason}}`, `Session → View session in OpenCX` with **Link** set to the same session URL as the comment

* **Call Tags**: `opencx`

<Tip>
  The whole note is just workflow text — edit the template, reorder sections, or drop any of them. Newlines in the comment are preserved in the Aircall note, so you can format it into sections. Generating the summary as a workflow step (instead of baking it into the trigger) means transfers that don't post context to Aircall never pay for summarization.
</Tip>

<Note>
  Aircall call comments are plain text — no markdown or HTML. Include links as full raw URLs (as in the template above). For a guaranteed clickable link during the call, use an insight card field's **Link** input, which Aircall renders as a native hyperlink in the agent's phone app. `{{trigger.ticket.ticketId}}` is the OpenCX session UUID, so `https://platform.open.cx/inbox/?s={{trigger.ticket.ticketId}}&org={{organization.id}}` deep-links straight to the session in the inbox.
</Note>

## Inputs reference

<AccordionGroup>
  <Accordion title="Aircall API ID / API Token" icon="key">
    Required. The API key pair from your [Aircall dashboard](https://dashboard.aircall.io/view-api-keys). Sent as HTTP Basic auth.
  </Accordion>

  <Accordion title="Caller Phone Number" icon="phone">
    Required. The number used to search Aircall for the transferred call. Usually `{{trigger.ticket.contact.phone_number}}`. Both `+`-prefixed (E.164) and bare-digit spellings are tried automatically, E.164 first.
  </Accordion>

  <Accordion title="Call Comment" icon="note-sticky">
    Optional. Posted as a note on the Aircall call record; persists after the call ends.

    <Warning>
      Aircall allows at most **5 comments per call** and comments cannot be edited or deleted once posted. Emojis are stripped by Aircall.
    </Warning>
  </Accordion>

  <Accordion title="Insight Card Title / Fields" icon="id-card">
    Optional. Builds the card shown in the agent's Aircall phone app **during** the call — it is not stored after the call ends. Each field is a `{ label, text, link }` line; the whole card payload must stay under **10KB** (the action validates this before posting).
  </Accordion>

  <Accordion title="Call Tags" icon="tag">
    Optional. Tag names to add to the Aircall call (e.g. `opencx`). Tags that don't exist in your Aircall account yet are created automatically; existing tags are matched case-insensitively so no duplicates are created. Tags already on the call are kept.
  </Accordion>

  <Accordion title="Max Wait (seconds)" icon="clock">
    Defaults to `30` (maximum `40`). A freshly transferred call can take a few seconds to become searchable in Aircall, so the action polls every few seconds until it finds the call or this budget runs out. Set to `0` to try exactly once.
  </Accordion>
</AccordionGroup>

## How the call is matched

The action searches Aircall's call log for the caller's number, newest call first, bounded to the last 15 minutes:

1. Every spelling of the number is tried — `+13025494224` first (Aircall stores E.164), then `13025494224` — so it doesn't matter which format your contact record uses.
2. If the search comes back empty, the action waits a few seconds and retries until **Max Wait** elapses, absorbing Aircall's search-indexing lag.
3. Among matches, calls that are still **ringing or ongoing** win — the transferred call is by definition live when the workflow fires — so an older, already-ended call from the same number can never shadow the fresh transfer. Among those, inbound calls are preferred, then the newest.

## Output

| Key | Meaning |
| - | - |
| `success` | `true` when everything requested was posted. |
| `callId` | The Aircall call ID the context was attached to. |
| `commentPosted` | Whether a comment was posted. |
| `insightCardPosted` | Whether an insight card was displayed. |
| `tagsApplied` | How many tags were set on the call. |
| `lookupAttempts` | How many search rounds it took to find the call. |

## Good To Know

<AccordionGroup>
  <Accordion title="Insight cards are ephemeral" icon="hourglass-half">
    Aircall only shows insight cards on **ongoing** calls and discards them when the call ends. For context that must survive the call, use the comment as well.
  </Accordion>

  <Accordion title="Credential storage and rotation" icon="key">
    The API ID and token are read from the node's configuration on every run. Reference [organization variables](/integrations/aircall/connect#store-as-organization-variables) (`{{variables.aircall_api_id}}` / `{{variables.aircall_api_token}}`) instead of pasting raw values — then rotating the key is a one-place change in **Settings → Variables**, and no workflow needs editing.
  </Accordion>

  <Accordion title="Errors surface as run failures" icon="triangle-exclamation">
    Bad credentials, no matching call within the wait budget, or a rejected post (e.g. the 6th comment on a call) fail the workflow run on this node with a descriptive error — nothing is swallowed silently.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Connect" icon="plug" href="/integrations/aircall/connect">
    Generate the Aircall API ID and token.
  </Card>

  <Card title="Overview" icon="phone" href="/integrations/aircall/overview">
    How the transfer + context flow fits together.
  </Card>

  <Card title="AI Phone agent configuration" icon="gear" href="/phone/agent-config">
    Add the transfer destination that forwards calls to Aircall.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/aircall/troubleshooting">
    Call not found, credential errors, comment limits.
  </Card>
</CardGroup>


# Aircall troubleshooting
Source: https://docs.open.cx/integrations/aircall/troubleshooting

Debug Aircall workflow errors: call not found after transfer, rejected credentials, comment limits, and oversized insight cards.

Before debugging, have this ready:

* The **workflow run ID** from your [OpenCX dashboard](https://platform.open.cx) (run viewer → failed run).
* The **caller's phone number** for the failed transfer.
* Whether the call actually shows up in Aircall's own call history.

<Tip>
  The workflow run viewer shows each node's input and output. Most Aircall failures surface there as a descriptive error on the action — read it before assuming the integration is down.
</Tip>

## Common scenarios

### **"No recent Aircall call found for phone number …"**

<Tooltip>Likely cause</Tooltip>: OpenCX couldn't find the transferred call under the caller's number.

**Fix:**

* Make sure **Caller Phone Number** is set to `{{trigger.ticket.contact.phone_number}}` — the customer's number, not your Aircall number.
* If new calls take a while to appear in Aircall, raise **Max Wait (seconds)** so OpenCX keeps looking a bit longer.
* Open the call in Aircall's call history. If the caller shows as **anonymous** or an unknown number, [contact us](#none-of-the-above) — that's something we need to fix on our side.

### **Action fails with "Aircall rejected the credentials (401/403)"**

<Tooltip>Likely cause</Tooltip>: a typo in the API ID/token, or the key was revoked.

**Fix:** re-run the ping check from [Connect](/integrations/aircall/connect#verify-the-connection). If it fails, generate a fresh key from the [Aircall API Keys page](https://dashboard.aircall.io/view-api-keys) and update the `aircall_api_id` / `aircall_api_token` [organization variables](/integrations/aircall/connect#store-as-organization-variables) — or the workflow node itself if the values were pasted in directly.

### **The comment fails to post**

<Tooltip>Likely cause</Tooltip>: the call already has 5 comments — Aircall's maximum — for example, because the workflow fired more than once for the same transfer.

**Fix:** keep one context-posting workflow per transfer path. If you need multiple pieces of context, combine them into a single comment instead of posting several.

### **"Insight card payload exceeds the 10KB limit"**

<Tooltip>Likely cause</Tooltip>: one of the card's fields contains a very large value — typically a full transcript.

**Fix:** put summaries on the card, not transcripts. If the agent needs more detail, add a field with a **Link** to the OpenCX session and keep the card text short. Long context belongs in the call comment.

### **The card never shows up in the agent's phone app**

<Tooltip>Likely cause</Tooltip>: the card was posted after the call ended (e.g. a very short call, or a long **Max Wait**).

**Fix:** treat the card as best-effort garnish and keep the comment as the durable record. Shorter comment content and a low **Max Wait** get the card up faster.

### **None of the above**

Send your OpenCX contact the failing **workflow run ID** and the **caller phone number** (redact the API token from any screenshots). We'll trace from there.

## Limits & timing

| | Value |
| - | - |
| **Per-request HTTP timeout** | 30 seconds for each Aircall API call |
| **Call lookup budget** | **Max Wait (seconds)** input, default 30s, max 40s, polling every 3s |
| **Search window** | Calls created in the last 15 minutes |
| **Comments per call** | 5 (Aircall limit; comments are immutable) |
| **Insight card payload** | 10KB max (Aircall limit) |

***

## Related Documentation

<CardGroup>
  <Card title="Connect" icon="plug" href="/integrations/aircall/connect">
    Re-verify the API ID and token.
  </Card>

  <Card title="Post Call Context Action" icon="phone-forwarded" href="/integrations/aircall/post-call-context-action">
    Inputs, matching rules, and output reference.
  </Card>

  <Card title="Overview" icon="phone" href="/integrations/aircall/overview">
    How the transfer + context flow fits together.
  </Card>

  <Card title="AI Phone agent configuration" icon="gear" href="/phone/agent-config">
    Transfer destinations on the phone agent.
  </Card>
</CardGroup>


# AI Fields
Source: https://docs.open.cx/integrations/creatio/ai-fields

Configure OpenCX to auto-fill Creatio case fields like priority, category, and custom fields based on conversation context.

When a conversation is handed off and a Creatio case is created, OpenCX can automatically fill case fields based on the conversation. Your agents see cases that already have the right priority, category, or custom field values — reducing manual triage.

<Note>
  AI fields are filled at the time of case creation during handoff. The AI reads the full conversation transcript and uses your description of each field to determine the appropriate value.
</Note>

## How it works

<Steps>
  <Step title="You define field mappings">
    For each Creatio case field you want the AI to fill, provide the field name, a display title, the field type, and an AI description explaining how to determine the value.
  </Step>

  <Step title="Customer chats with the AI">
    The conversation progresses normally. The AI resolves what it can.
  </Step>

  <Step title="Handoff triggers auto-fill">
    When the AI escalates, it reads the full conversation and uses your descriptions to determine a value for each configured field.
  </Step>

  <Step title="Case is created with pre-filled fields">
    The Creatio case is created with the AI-determined values already set. Your agent opens a fully triaged case.
  </Step>
</Steps>

## Adding a field mapping

Each mapping requires:

| Property | Description | Example |
| - | - | - |
| **Field Name** | The Creatio entity column name | `PriorityId` |
| **Display Title** | Human-readable label | `Priority` |
| **Field Type** | `text` or `dropdown` | `dropdown` |
| **AI Description** | Instructions for the AI on how to determine the value | See examples below |

## Field types

<AccordionGroup>
  <Accordion title="Text fields" icon="font">
    Free-form text values. Use for fields like order number, product name, or any custom text column on the Case entity. The AI writes a short value based on the conversation.
  </Accordion>

  <Accordion title="Dropdown fields" icon="list">
    Predefined values. Use for fields like priority, category, or any lookup column. The AI selects the best matching value from the options you describe. List every allowed value in the AI description so the AI picks from your actual options.
  </Accordion>
</AccordionGroup>

## Writing effective AI descriptions

The AI description is the most important part of the mapping. It tells the AI how to analyze the conversation and pick the right value. Good descriptions are specific, give clear criteria, and list every possible value.

<AccordionGroup>
  <Accordion title="Priority (dropdown)" icon="flag">
    ```
    Determine the case priority based on urgency and impact:
    - "Critical" if the customer reports a complete system outage, data loss, or security breach
    - "High" if there's a significant workflow disruption affecting multiple users
    - "Medium" if a single user is affected by a bug or non-critical issue
    - "Low" if this is a feature request, question, or cosmetic issue
    ```
  </Accordion>

  <Accordion title="Category (dropdown)" icon="tag">
    ```
    Categorize based on the main topic:
    - "Billing" for payment issues, refunds, subscription changes, invoices
    - "Technical" for bugs, errors, integrations, API problems
    - "Account" for login issues, password resets, account changes
    - "Shipping" for delivery tracking, lost packages, address changes
    - "General" if none of the above fit
    ```
  </Accordion>

  <Accordion title="Order Number (text)" icon="hashtag">
    ```
    Extract the order number from the conversation if the customer mentions one.
    Order numbers typically look like "ORD-12345" or "#12345".
    If no order number is mentioned, leave blank.
    ```
  </Accordion>
</AccordionGroup>

## Good to know

<AccordionGroup>
  <Accordion title="Be explicit about every value" icon="bullseye">
    List every possible value and when to use it. The AI does not infer your categories — it picks from what you describe.
  </Accordion>

  <Accordion title="Handle ambiguous cases" icon="shield">
    Specify what the AI should do when the conversation is unclear — pick a default value or leave blank. Without guidance, the AI may skip the field.
  </Accordion>

  <Accordion title="Field names are case-sensitive" icon="text-size">
    The field name must match the exact Creatio column name. `PriorityId` and `priorityid` are different. Check the column name in Creatio's object designer.
  </Accordion>

  <Accordion title="Changes take effect immediately" icon="bolt">
    Updating an AI description applies to the next handoff. No restart or redeployment needed. Existing cases are not affected.
  </Accordion>
</AccordionGroup>

## Managing field mappings

Each field mapping can be individually **enabled** or **disabled**. Disabled fields are not evaluated during handoff — useful for temporarily pausing a field without deleting its configuration.

**Deleting** a field mapping removes it permanently. Existing cases that were already filled are not affected.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Creatio" icon="plug" href="/integrations/creatio/connect">
    Credentials and optional routing settings.
  </Card>

  <Card title="Case Sync" icon="arrows-rotate" href="/integrations/creatio/case-sync">
    Case creation, message sync, and two-way webhooks.
  </Card>

  <Card title="Creatio overview" icon="grid-2" href="/integrations/creatio/overview">
    Capabilities, supported channels, and observability.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/creatio/troubleshooting">
    AI fields blank, wrong values, field name mismatch.
  </Card>
</CardGroup>


# Case Sync
Source: https://docs.open.cx/integrations/creatio/case-sync

Understand how Creatio cases are created, what data syncs in each direction, and how to set up two-way communication via business process webhooks.

Once [connected](/integrations/creatio/connect), OpenCX creates and updates Creatio cases as conversations progress. This page covers what happens automatically and what requires a Creatio business process on your side.

## How case creation works

```mermaid theme={"dark"}
flowchart LR
  A[Contact message] --> B{AI can resolve?}
  B -- Yes --> C[AI replies on channel]
  B -- No --> D[Handoff]
  D --> E[Create or update Creatio case]
  E --> F[Rep replies in Creatio]
  F --> G[Reply syncs back to contact]
```

When <Tooltip href="/handoff/introduction">handoff</Tooltip> triggers, OpenCX:

1. Creates a case in your Creatio instance with the session ID, conversation summary, and customer details.
2. Logs the full transcript as case activities — one activity per message.
3. Auto-fills any fields you've [mapped](/integrations/creatio/ai-fields).
4. Assigns to the **Default Case Owner** or **Default Case Group** if configured.

If a case already exists for this conversation, the handoff note is added as a new activity instead of creating a duplicate.

## Case creation modes

| Mode | Behavior |
| - | - |
| **On every conversation** (default) | A case is created when the first customer message arrives. Every message and AI reply is logged as an activity in real time. |
| **On handoff only** | A case is created only when the AI escalates. Best for teams that want Creatio involved only for issues the AI cannot resolve. |

Switch between modes in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Creatio → **Create case only on handoff**.

## What syncs in each direction

| OpenCX to Creatio | Creatio to OpenCX |
| - | - |
| Customer messages (as activities) | Agent replies (via webhook) |
| AI replies (as activities) | Case closure (via webhook) |
| Handoff summary, language, sentiment | |
| AI-filled fields | |
| Resolution status | |

<Note>
  Creatio-to-OpenCX sync requires business processes you configure in Creatio. Without them, the integration is one-directional — OpenCX writes to Creatio, but agent replies and case closures do not flow back.
</Note>

## Setting up two-way sync

Two-way sync lets your agents reply from Creatio and have those replies reach the customer, and lets case closures in Creatio resolve the OpenCX conversation. Both require a Creatio <Tooltip>business process</Tooltip> that sends an HTTP request to OpenCX.

### Get your webhook URL

<Steps>
  <Step title="Open integration settings">
    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), go to **Settings → Integrations** → **Creatio**.
  </Step>

  <Step title="Copy the webhook URL">
    Your unique webhook URL is displayed on the integration page. Copy it — you will paste it into the Creatio business processes below.

    <Warning>
      This URL contains a secret token. Do not share it publicly.
    </Warning>
  </Step>
</Steps>

### Create a business process for agent replies

This process fires when an agent adds a reply to a case, delivering the message to the customer through their original channel.

<Steps>
  <Step title="Open the Process Designer">
    In Creatio, go to **System Designer → Process Library → Add Process**.
  </Step>

  <Step title="Set the trigger">
    Add a **Signal** start event:

    * **Object**: `Activity`
    * **Event**: `After record added`
    * **Filter**: Match how your agents add replies (e.g. `Type = Task` or `Type = Email`)

    <Tip>
      Filter by the activity's parent case to avoid triggering on unrelated activities.
    </Tip>
  </Step>

  <Step title="Add a web service call">
    Drag in a **Call web service** element and configure:

    * **URL**: Paste your OpenCX webhook URL
    * **Method**: `POST`
    * **Content Type**: `application/json`
    * **Request body**:

    ```json theme={"dark"}
    {
      "event_type": "new_activity",
      "caseId": "[#Case.Id#]"
    }
    ```

    Replace `[#Case.Id#]` with the process parameter referencing the related Case ID. The exact syntax depends on how you linked the Activity to its Case in the process.
  </Step>

  <Step title="Save and activate">
    Save the process and set it to **Active**. Test by adding a reply to a case created by OpenCX — the message should appear in the customer's chat within seconds.
  </Step>
</Steps>

### Create a business process for case closure

This process fires when a case is resolved in Creatio, closing the matching OpenCX conversation.

<Steps>
  <Step title="Create a new process">
    Add another process in the Process Library.
  </Step>

  <Step title="Set the trigger">
    Add a **Signal** start event:

    * **Object**: `Case`
    * **Event**: `After record modified`
    * **Filter**: `Status = Resolved` (match your resolved status name exactly)
  </Step>

  <Step title="Add a web service call">
    Configure:

    * **URL**: Your OpenCX webhook URL
    * **Method**: `POST`
    * **Content Type**: `application/json`
    * **Request body**:

    ```json theme={"dark"}
    {
      "event_type": "case_closed",
      "caseId": "[#Case.Id#]"
    }
    ```
  </Step>

  <Step title="Save and activate">
    Save and activate. Test by resolving a case in Creatio — the corresponding OpenCX conversation should close automatically.
  </Step>
</Steps>

### Webhook event reference

| Event type | When to send | What happens in OpenCX |
| - | - | - |
| `new_activity` | Agent adds a reply to a case | The reply is delivered to the customer on their original channel |
| `case_closed` | Case status changes to resolved/closed | The OpenCX conversation is marked as resolved |
| `case_updated` | Case is modified (reserved for future use) | Acknowledged but no action taken |

All webhook requests must be `POST` with a JSON body containing `event_type` (string) and `caseId` (string — the Creatio Case GUID).

### Verify webhooks

<Steps>
  <Step title="Test agent reply sync">
    Have an agent add a reply to a case that was created by OpenCX. Confirm the message appears in the customer's chat.
  </Step>

  <Step title="Test case closure sync">
    Resolve a case in Creatio. Confirm the corresponding conversation in OpenCX is marked as resolved.
  </Step>
</Steps>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Creatio" icon="plug" href="/integrations/creatio/connect">
    Credentials, optional routing settings, and verification.
  </Card>

  <Card title="AI Fields" icon="wand-magic-sparkles" href="/integrations/creatio/ai-fields">
    Auto-fill case fields from conversation context.
  </Card>

  <Card title="Creatio overview" icon="grid-2" href="/integrations/creatio/overview">
    Capabilities, supported channels, and observability.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/creatio/troubleshooting">
    Webhook errors, replies not syncing, case closure issues.
  </Card>
</CardGroup>


# AI Email Support in Creatio
Source: https://docs.open.cx/integrations/creatio/channels/email

Route email conversations into Creatio as cases so your reps work them from their existing queue.

Email conversations route through to Creatio as cases. When the AI hands off an email thread, your rep picks up the case with the full email history and AI-filled fields already attached.

## Pre-requisites

<Warning>
  **Set up email forwarding first.** Creatio handoff has nothing to route until inbound email is reaching OpenCX — start with [Connect Email](/email/forwarding) and come back here.
</Warning>

* **Email forwarding configured** — see [Connect Email](/email/forwarding).
* **Creatio credentials saved and verified** — see [Connect Creatio](/integrations/creatio/connect).

## How conversations land in Creatio

```mermaid theme={"dark"}
flowchart LR
  A[Customer emails your support address] --> B[AI replies from the same address]
  B --> C{AI can resolve?}
  C -- Yes --> D[Thread stays email-only]
  C -- No --> E[Handoff]
  E --> F[Creatio case created with email thread]
  F --> G[Rep replies — lands in customer inbox]
```

## Setting up

<Steps>
  <Step title="Confirm email forwarding works">
    Open [**Channels → AI Email**](https://platform.open.cx/channels/configure/mail) in the OpenCX dashboard. Your forwarding address should be listed and verified. Send a test email and confirm it reaches the [Inbox](https://platform.open.cx/inbox).
  </Step>

  <Step title="Confirm Creatio is connected">
    In [Settings → Integrations](https://platform.open.cx/settings/integrations), open **Creatio**. The status should show **Active**.
  </Step>

  <Step title="Trigger a test handoff">
    Send a test email to your connected address and respond with something that causes the AI to escalate. Alternatively, manually hand off the session from the [Inbox](https://platform.open.cx/inbox).
  </Step>

  <Step title="Verify the case in Creatio">
    A new case should appear with:

    * The conversation summary as the case description
    * The full email thread as case activities
    * Any [AI-filled fields](/integrations/creatio/ai-fields) pre-populated
    * Assignment to the default owner or group (if configured)
  </Step>

  <Step title="Reply and verify sync">
    If you set up the [webhook business process](/integrations/creatio/case-sync#create-a-business-process-for-agent-replies), have an agent reply on the case in Creatio. Confirm the reply arrives in the customer's email inbox and shows as an agent message in the [OpenCX Inbox](https://platform.open.cx/inbox).
  </Step>
</Steps>

## What the rep sees

* A **Creatio case** with the conversation summary as the description.
* The **full email thread** as individual case activities.
* **AI-filled fields** pre-populated on mapped fields.
* A **View session in OpenCX** link in the first activity.
* Replies posted in Creatio (via the [webhook business process](/integrations/creatio/case-sync#create-a-business-process-for-agent-replies)) reach the customer's email inbox.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Case-append on returning contacts" icon="rotate">
    If the same contact sends another email before the case is closed, OpenCX appends to the existing case instead of creating a new one. Your reps keep context in a single case.
  </Accordion>

  <Accordion title="Attachments" icon="paperclip">
    Attachments the customer sends by email are included in the conversation context. References to attachments appear in the case activities.
  </Accordion>

  <Accordion title="Email thread formatting" icon="align-left">
    Each email in the thread is logged as a separate activity on the Creatio case. Quoted reply text is trimmed so activities show only the new content from each message.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Email Support" icon="envelope" href="/email/introduction">
    The channel itself — forwarding setup, flow, troubleshooting.
  </Card>

  <Card title="Connect Creatio" icon="plug" href="/integrations/creatio/connect">
    Credentials, optional settings, and verification.
  </Card>

  <Card title="Creatio overview" icon="grid-2" href="/integrations/creatio/overview">
    Capabilities and supported channels.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/creatio/troubleshooting">
    Cases not creating, replies missing, sync stuck.
  </Card>
</CardGroup>


# AI Phone Support in Creatio
Source: https://docs.open.cx/integrations/creatio/channels/phone

Route phone conversations into Creatio as cases with the call transcript attached.

Phone conversations route through to Creatio as cases. When the AI voice agent hands off or finishes a call, your rep picks up the case with the call transcript and AI-filled fields already attached.

## Pre-requisites

<Warning>
  **Create a phone agent first.** Creatio handoff has nothing to route until a voice agent is live — start with [Create a Phone Agent](/phone/create-agent) and come back here.
</Warning>

* **Phone agent created and a number assigned** — see [Create a Phone Agent](/phone/create-agent).
* **Creatio credentials saved and verified** — see [Connect Creatio](/integrations/creatio/connect).

## How conversations land in Creatio

```mermaid theme={"dark"}
flowchart LR
  A[Customer calls your number] --> B[AI voice agent answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Call ends]
  C -- No --> E[Handoff]
  E --> F[Creatio case created with transcript]
  F --> G[Rep follows up from Creatio]
```

## Setting up

<Steps>
  <Step title="Confirm phone is connected">
    In your [OpenCX dashboard](https://platform.open.cx/settings/phone-numbers), confirm your phone number is listed. Make a test call and confirm the AI voice agent answers.
  </Step>

  <Step title="Confirm Creatio is connected">
    In [Settings → Integrations](https://platform.open.cx/settings/integrations), open **Creatio**. The status should show **Active**.
  </Step>

  <Step title="Trigger a test handoff">
    Call your connected number and request a human agent. The AI should hand off the conversation.
  </Step>

  <Step title="Verify the case in Creatio">
    A new case should appear with the call transcript as activities and any AI-filled fields populated.
  </Step>
</Steps>

## What the rep sees

* A **Creatio case** with the conversation summary.
* The **call transcript** as case activities, showing what both the customer and the AI said.
* **AI-filled fields** pre-populated on mapped fields.
* A **View session in OpenCX** link in the first activity — one click opens the full session with audio playback (if recordings are enabled).

## Channel-specific details

<AccordionGroup>
  <Accordion title="Transcript timing" icon="clock">
    The call transcript is finalized and attached to the Creatio case after the call ends. During a live transfer, the transcript up to the transfer point is attached; the remainder is added when the transferred call ends.
  </Accordion>

  <Accordion title="Live transfer vs logged handoff" icon="phone-arrow-right">
    If the AI transfers the call to a human agent in real time, the customer stays on the line. If the AI logs the handoff without transferring, the call ends and a case is created for follow-up. The case indicates which path was taken.
  </Accordion>

  <Accordion title="Recordings" icon="microphone">
    If call recordings are enabled in OpenCX, the recording is accessible from the session link in the first case activity. Recordings are not uploaded directly to Creatio.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Phone Support" icon="phone" href="/phone/introduction">
    The channel itself — create agents, configure numbers, inbound and outbound.
  </Card>

  <Card title="Connect Creatio" icon="plug" href="/integrations/creatio/connect">
    Credentials, optional settings, and verification.
  </Card>

  <Card title="Creatio overview" icon="grid-2" href="/integrations/creatio/overview">
    Capabilities and supported channels.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/creatio/troubleshooting">
    Cases not creating, transcript missing, sync stuck.
  </Card>
</CardGroup>


# AI SMS Support in Creatio
Source: https://docs.open.cx/integrations/creatio/channels/sms

Route SMS conversations into Creatio as cases so your reps work them from their existing queue.

SMS conversations route through to Creatio as cases. When the AI hands off, your rep picks up the case with the full message thread and AI-filled fields already attached.

## Pre-requisites

<Warning>
  **Connect your SMS number first.** Creatio handoff has nothing to route until SMS is live — start with [Connect SMS](/sms/connect-sms) and come back here.
</Warning>

* **SMS number connected** — see [Connect SMS](/sms/connect-sms).
* **Creatio credentials saved and verified** — see [Connect Creatio](/integrations/creatio/connect).

## How conversations land in Creatio

```mermaid theme={"dark"}
flowchart LR
  A[Customer texts your number] --> B[AI replies via SMS]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation ends]
  C -- No --> E[Handoff]
  E --> F[Creatio case created with transcript]
  F --> G[Rep replies — lands as SMS]
```

## Setting up

<Steps>
  <Step title="Confirm SMS is connected">
    In your [OpenCX dashboard](https://platform.open.cx/channels/sms), confirm your SMS number is listed and verified. Send a test message and confirm the AI responds.
  </Step>

  <Step title="Confirm Creatio is connected">
    In [Settings → Integrations](https://platform.open.cx/settings/integrations), open **Creatio**. The status should show **Active**.
  </Step>

  <Step title="Trigger a test handoff">
    Text your connected number with something the AI cannot resolve (e.g. *"I need to speak with a person"*). Alternatively, manually hand off the session from the [Inbox](https://platform.open.cx/inbox).
  </Step>

  <Step title="Verify the case in Creatio">
    A new case should appear with the conversation summary, activities for each message, and any AI-filled fields populated.
  </Step>
</Steps>

## What the rep sees

* A **Creatio case** with the conversation summary and customer's phone number.
* The **full transcript** as individual case activities.
* **AI-filled fields** pre-populated on mapped fields.
* A **View session in OpenCX** link in the first activity.
* Replies posted in Creatio (via the [webhook business process](/integrations/creatio/case-sync#create-a-business-process-for-agent-replies)) reach the customer as SMS messages.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Message length and segmentation" icon="scissors">
    SMS messages longer than 160 characters are split into multiple segments by the carrier. Your rep's reply from Creatio is delivered as a single logical message, but long replies may incur additional carrier costs.
  </Accordion>

  <Accordion title="10DLC and toll-free compliance" icon="flag">
    If you are sending SMS to US numbers, your number must be registered for 10DLC or toll-free verification. Non-compliant numbers may have messages filtered by carriers. See [SMS Compliance](/sms/compliance).
  </Accordion>

  <Accordion title="Contact identity" icon="user">
    The customer's phone number is used to match or create a contact in OpenCX. If the same number maps to an existing contact, the case is linked to that contact record.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI SMS Support" icon="comment-sms" href="/sms/introduction">
    The channel itself — connect, configure, compliance.
  </Card>

  <Card title="Connect Creatio" icon="plug" href="/integrations/creatio/connect">
    Credentials, optional settings, and verification.
  </Card>

  <Card title="Creatio overview" icon="grid-2" href="/integrations/creatio/overview">
    Capabilities and supported channels.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/creatio/troubleshooting">
    Cases not creating, replies missing, sync stuck.
  </Card>
</CardGroup>


# AI WhatsApp Support in Creatio
Source: https://docs.open.cx/integrations/creatio/channels/whatsapp

Route WhatsApp conversations into Creatio as cases so your reps continue working from their existing queue.

WhatsApp conversations route through to Creatio as cases. When the AI hands off, your rep picks up the case with the full WhatsApp thread and AI-filled fields already attached.

## Pre-requisites

<Warning>
  **Connect your WhatsApp number first.** Creatio handoff has nothing to route until WhatsApp is live — start with [Connect WhatsApp](/whatsapp/connect-whatsapp) and come back here.
</Warning>

* **WhatsApp number connected** — see [Connect WhatsApp](/whatsapp/connect-whatsapp).
* **Creatio credentials saved and verified** — see [Connect Creatio](/integrations/creatio/connect).

## How conversations land in Creatio

```mermaid theme={"dark"}
flowchart LR
  A[Customer messages on WhatsApp] --> B[AI replies]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation ends on WhatsApp]
  C -- No --> E[Handoff]
  E --> F[Creatio case created with transcript]
  F --> G[Rep replies — lands on WhatsApp]
```

## Setting up

<Steps>
  <Step title="Confirm WhatsApp is connected">
    In your [OpenCX dashboard](https://platform.open.cx/channels), confirm your WhatsApp number is listed and active. Send a test message and confirm the AI responds.
  </Step>

  <Step title="Confirm Creatio is connected">
    In [Settings → Integrations](https://platform.open.cx/settings/integrations), open **Creatio**. The status should show **Active**.
  </Step>

  <Step title="Trigger a test handoff">
    Send a WhatsApp message that causes the AI to escalate (e.g. *"I need to speak with a person"*). Alternatively, manually hand off the session from the [Inbox](https://platform.open.cx/inbox).
  </Step>

  <Step title="Verify the case in Creatio">
    A new case should appear with the conversation summary, activities for each message, and any AI-filled fields populated.
  </Step>
</Steps>

## What the rep sees

* A **Creatio case** with the conversation summary and customer's WhatsApp contact info.
* The **full transcript** as individual case activities.
* **AI-filled fields** pre-populated on mapped fields.
* A **View session in OpenCX** link in the first activity.
* Replies posted in Creatio (via the [webhook business process](/integrations/creatio/case-sync#create-a-business-process-for-agent-replies)) reach the customer on WhatsApp.

## Channel-specific details

<AccordionGroup>
  <Accordion title="24-hour messaging window" icon="clock">
    WhatsApp enforces a 24-hour window from the customer's last message. If the rep replies after the window closes, the message may not be delivered. Respond promptly or use a WhatsApp-approved template message to re-open the window.
  </Accordion>

  <Accordion title="Media and attachments" icon="image">
    Images, documents, and voice notes sent by the customer on WhatsApp are included in the conversation context. References to these appear in the case activities.
  </Accordion>

  <Accordion title="Contact identity" icon="user">
    The customer's WhatsApp phone number is used to match or create a contact in OpenCX. If the same number maps to an existing contact, the case is linked to that contact record.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI WhatsApp Support" icon="whatsapp" href="/whatsapp/introduction">
    The channel itself — connect, configure, compliance.
  </Card>

  <Card title="Connect Creatio" icon="plug" href="/integrations/creatio/connect">
    Credentials, optional settings, and verification.
  </Card>

  <Card title="Creatio overview" icon="grid-2" href="/integrations/creatio/overview">
    Capabilities and supported channels.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/creatio/troubleshooting">
    Cases not creating, replies missing, sync stuck.
  </Card>
</CardGroup>


# AI Chat Widget in Creatio
Source: https://docs.open.cx/integrations/creatio/channels/widget

Route AI Chat Widget conversations into Creatio as cases with the full transcript attached.

Widget conversations route through to Creatio as cases. When the AI hands off a chat, your rep picks it up as a case in Creatio with the full transcript and AI-filled fields already attached.

## Pre-requisites

<Warning>
  **Install the AI Chat Widget on your site first.** Creatio handoff has nothing to route until the widget is live — start with [Install Widget](/widget/install-widget) and come back here.
</Warning>

* **Widget installed and reachable** — see [Install Widget](/widget/install-widget).
* **Creatio credentials saved and verified** — see [Connect Creatio](/integrations/creatio/connect).

## How conversations land in Creatio

```mermaid theme={"dark"}
flowchart LR
  A[Visitor opens widget] --> B[AI answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Visitor closes the chat]
  C -- No --> E[Handoff]
  E --> F[Creatio case created with transcript]
  F --> G[Rep replies — lands in the widget]
```

## Setting up

<Steps>
  <Step title="Confirm the widget is live">
    Open the page where you embedded the widget and send a test message. You should see the AI respond. If the widget does not load, walk through [Install Widget](/widget/install-widget) first.
  </Step>

  <Step title="Confirm Creatio is connected">
    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), open **Creatio**. The status should show **Active**. If not, complete the [Connect Creatio](/integrations/creatio/connect) setup.
  </Step>

  <Step title="Trigger a test handoff">
    Send a message like *"I want to talk to a human"* in the widget. The AI should hand off the conversation.
  </Step>

  <Step title="Verify the case in Creatio">
    Open your Creatio instance. A new case should appear with:

    * The conversation summary as the case description
    * Each message logged as a case activity
    * Any [AI-filled fields](/integrations/creatio/ai-fields) pre-populated
    * Assignment to the default owner or group (if configured)
  </Step>
</Steps>

## What the rep sees

* A **Creatio case** with the conversation summary as the description.
* The **full transcript** as individual activities on the case timeline.
* **AI-filled fields** pre-populated on the fields you mapped at [Settings → Integrations](https://platform.open.cx/settings/integrations).
* A **View session in OpenCX** link in the first activity — one click opens the full AI reasoning and handoff event.
* Replies posted in Creatio (via the [webhook business process](/integrations/creatio/case-sync#create-a-business-process-for-agent-replies)) land back in the visitor's widget.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Authenticated visitors vs anonymous visitors" icon="shield-check">
    When the widget passes a verified email via [widget authentication](/widget/authentication), the contact in OpenCX is matched by email. Anonymous visitors are tracked by session until they identify themselves.
  </Accordion>

  <Accordion title="Files visitors upload" icon="paperclip">
    Files uploaded in the widget are included in the conversation context. The content is referenced in the case activities.
  </Accordion>

  <Accordion title="Custom components still render on the visitor side" icon="bolt">
    When an AI action returns data rendered by a [custom component](/widget/custom-components), the visitor sees the richer UI. Your rep sees the underlying text in Creatio case activities.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Chat Widget" icon="messages" href="/widget/introduction">
    The channel itself — install, configure, authenticate.
  </Card>

  <Card title="Connect Creatio" icon="plug" href="/integrations/creatio/connect">
    Credentials, optional settings, and verification.
  </Card>

  <Card title="Creatio overview" icon="grid-2" href="/integrations/creatio/overview">
    Capabilities and supported channels.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/creatio/troubleshooting">
    Cases not creating, replies missing, sync stuck.
  </Card>
</CardGroup>


# Connect Creatio
Source: https://docs.open.cx/integrations/creatio/connect

Create an OAuth application in Creatio, enter credentials in OpenCX, configure optional routing settings, and verify the connection.

One-time setup: create an OAuth application in Creatio, enter your credentials in OpenCX, configure optional case routing, and verify.

<CreatioFlow />

<Info>
  Setup takes about 15 minutes. You need admin access on both sides — your Creatio instance and your OpenCX organization.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Creatio instance with the Service module" icon="circle-check">
    The integration creates cases in Creatio's Service module. Confirm your instance has it enabled (e.g. `https://yourcompany.creatio.com`).
  </Accordion>

  <Accordion title="Admin access in Creatio" icon="user-shield">
    You need to create an OAuth 2.0 application and confirm API access to the Case entity. Standard agent roles cannot reach these settings.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="key">
    Required to save integration settings in [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Create an OAuth 2.0 application in Creatio">
    In your Creatio instance, navigate to **System Designer → OAuth 2.0 integrated applications**.

    1. Click **Add application**.
    2. Set the **Name** to `OpenCX Integration`.
    3. Set the **Grant Type** to `Client Credentials`.
    4. Leave **Redirect URI** blank — not needed for client credentials.
    5. Save. Creatio displays the **Client ID** and **Client Secret**.
    6. **Copy both values immediately.**

    <Warning>
      The client secret is only shown once. If you lose it, you need to regenerate it.
    </Warning>
  </Step>

  <Step title="Open Creatio settings in OpenCX">
    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), go to **Settings → Integrations** and select **Creatio**.
  </Step>

  <Step title="Enter your credentials">
    | Field | Value |
    | - | - |
    | **Instance URL** | Your Creatio URL (e.g. `https://yourcompany.creatio.com`). Do not include a trailing slash. |
    | **Client ID** | From the OAuth application you just created. |
    | **Client Secret** | From the OAuth application you just created. |
  </Step>

  <Step title="Configure optional settings">
    These are optional but recommended for teams that want automated case routing:

    | Field | What it does |
    | - | - |
    | **Default Case Owner ID** | Creatio Contact GUID. Cases are assigned to this person on creation. |
    | **Default Case Group ID** | Creatio Group GUID. Cases are assigned to this group for team-based routing. |
    | **Resolved Status ID** | Creatio CaseStatus GUID used when OpenCX resolves a conversation. Required for two-way resolution sync. |
    | **Create case only on handoff** | When enabled, cases are only created when the AI escalates — not on every conversation. |

    <Tip>
      To find GUIDs, use Creatio's built-in lookup pages or query the relevant entity. For example, case statuses are at `https://yourcompany.creatio.com/0/odata/CaseStatus`.
    </Tip>
  </Step>

  <Step title="Verify and save">
    Click **Test & Save**. OpenCX authenticates with Creatio using your credentials. If the test passes, the connection is active.

    If it fails, jump to [Troubleshooting](/integrations/creatio/troubleshooting).
  </Step>
</Steps>

## Rotating credentials

Regenerating the OAuth client secret in Creatio invalidates the old one immediately. To rotate:

1. Generate a new client secret in Creatio's OAuth application settings.
2. Update the secret in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Creatio.
3. Click **Test & Save** to confirm the new credentials work.

## Disconnecting

In OpenCX, open the Creatio integration and click **Disconnect**. Cases created while the integration was active remain untouched in Creatio.

***

## Related Documentation

<CardGroup>
  <Card title="Case Sync" icon="arrows-rotate" href="/integrations/creatio/case-sync">
    How cases are created, what syncs, and how to set up two-way webhooks.
  </Card>

  <Card title="AI Fields" icon="wand-magic-sparkles" href="/integrations/creatio/ai-fields">
    Auto-fill case fields from conversation context.
  </Card>

  <Card title="Creatio overview" icon="grid-2" href="/integrations/creatio/overview">
    Capabilities, supported channels, and observability.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/creatio/troubleshooting">
    Credential errors, cases not creating, sync failures.
  </Card>
</CardGroup>


# Creatio overview
Source: https://docs.open.cx/integrations/creatio/overview

Run Creatio as the case management surface your agents work in while OpenCX resolves, routes, and hands off conversations with full context.

OpenCX works alongside your agents inside Creatio. The AI resolves what it can, escalates what it can't, and files every <Tooltip>handoff</Tooltip> straight into a Creatio case your reps already work from — with conversation summary, customer details, and AI-filled fields attached. No separate inbox, no context rebuild.

<Tip>
  Setup starts at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="Cases your reps pick up with full context" icon="ticket">
    When the AI escalates, OpenCX creates a Creatio case with the conversation summary as the description and every message logged as an activity. Your rep opens a case that already has everything they need — no copy-pasting from another tool.
  </Accordion>

  <Accordion title="Two-way message sync between your customers and agents" icon="arrows-rotate">
    Customer messages and AI replies flow into Creatio as case activities. When your agent replies in Creatio, the message travels back to the customer on whatever channel they wrote in — widget, WhatsApp, email, SMS, or phone.
  </Accordion>

  <Accordion title="AI-filled fields so your triage works on day one" icon="wand-magic-sparkles">
    Map any Creatio case field to a short description of what it represents. On handoff, OpenCX picks the value — dropdowns stay inside your existing options, text fields get structured strings. Your saved views, queues, and reports work without manual classification.
  </Accordion>

  <Accordion title="Flexible case creation modes" icon="sliders">
    Choose whether Creatio cases are created on every conversation (for full audit trails) or only when the AI escalates (for teams that want Creatio involved only on handoffs). Switch between modes from the dashboard without code changes.
  </Accordion>

  <Accordion title="Two-way resolution sync" icon="circle-check">
    Resolving a conversation in OpenCX closes the Creatio case. Resolving a case in Creatio closes the OpenCX conversation. Neither system gets out of sync.
  </Accordion>
</AccordionGroup>

## Supported channels

Pick the channel you want to wire through Creatio — each page covers the implementation details for that channel on top of the shared setup.

<CardGroup>
  <Card title="AI Chat Widget" icon="comments" href="/integrations/creatio/channels/widget">
    Live chat handoff into a Creatio case with the full transcript.
  </Card>

  <Card title="AI WhatsApp Support" icon="whatsapp" href="/integrations/creatio/channels/whatsapp">
    WhatsApp threads handed off as Creatio cases.
  </Card>

  <Card title="AI SMS Support" icon="comment-sms" href="/integrations/creatio/channels/sms">
    SMS conversations handed off as Creatio cases.
  </Card>

  <Card title="AI Phone Support" icon="phone" href="/integrations/creatio/channels/phone">
    Voice conversations with transcript attached to a Creatio case.
  </Card>

  <Card title="AI Email Support" icon="envelope" href="/integrations/creatio/channels/email">
    Email threads handed off as Creatio cases.
  </Card>
</CardGroup>

## Observability

Every conversation OpenCX hands to Creatio is traceable from the Creatio side back to the exact OpenCX session. Your reps debug in the tool they already work in; your admins audit without re-running the AI.

<AccordionGroup>
  <Accordion title="Session linked to every case" icon="fingerprint">
    OpenCX stores the session ID on each Creatio case it creates. Searching cases by this identifier surfaces the exact OpenCX conversation — useful when a rep needs to know "which conversation produced this case?"
  </Accordion>

  <Accordion title="Back-link to OpenCX in the first activity" icon="link">
    The first activity on every OpenCX-created case includes a **View session in OpenCX** link. One click opens the full transcript, tool calls, AI reasoning, and handoff event in your OpenCX Inbox — no case-ID lookup required.
  </Accordion>

  <Accordion title="Every message logged as a case activity" icon="list">
    Customer messages, AI replies, and handoff summaries are each logged as individual activities on the Creatio case. Your reps see the full conversation timeline without leaving Creatio.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Creatio" icon="plug" href="/integrations/creatio/connect">
    Credentials, optional settings, and verification.
  </Card>

  <Card title="Case Sync" icon="arrows-rotate" href="/integrations/creatio/case-sync">
    Case creation, message sync, and two-way webhooks.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/creatio/channels/widget">
    Per-channel implementation details.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/creatio/troubleshooting">
    Cases not creating, replies missing, sync stuck.
  </Card>
</CardGroup>


# Creatio troubleshooting
Source: https://docs.open.cx/integrations/creatio/troubleshooting

Debug Creatio connection, case creation, webhook, agent reply sync, and AI field issues.

Before debugging, have this ready:

* Your Creatio <Tooltip>instance URL</Tooltip> and the OAuth <Tooltip>client credentials</Tooltip>.
* A specific <Tooltip>session ID</Tooltip> (from [Inbox](https://platform.open.cx/inbox)) or Creatio case ID where the problem shows.
* The webhook URL shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Creatio.

<Tip>
  Re-run **Test & Save** in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Creatio as your first step. Most issues are credential or webhook related.
</Tip>

<Info>
  **Fastest path to root cause:** find the conversation in your [OpenCX Inbox](https://platform.open.cx/inbox) and check the session's AI reasoning, tool calls, and handoff event. That is far faster than inspecting business process logs.
</Info>

## Common scenarios

Jump to the symptom that matches what you are seeing.

### **"Invalid credentials" when saving**

<Tooltip>Likely cause</Tooltip>: wrong Instance URL format, expired or incorrect client secret, or the OAuth application is not using the Client Credentials grant type.

**Fix:** confirm the Instance URL does not have a trailing slash (use `https://yourcompany.creatio.com`, not `https://yourcompany.creatio.com/`). Regenerate the client secret in Creatio's OAuth application settings if needed. Confirm the grant type is **Client Credentials**.

### **Cases not being created**

<Tooltip>Likely cause</Tooltip>: handoff-only mode is enabled and the AI resolved the conversation, or the OAuth application lacks API access to the Case entity.

**Fix:** check [Settings → Integrations](https://platform.open.cx/settings/integrations) → Creatio. If **Create case only on handoff** is enabled, cases are created only when the AI escalates. To test, trigger a handoff manually from the [Inbox](https://platform.open.cx/inbox). Also confirm the OAuth application has permissions to create and update Case records in Creatio.

### **Agent replies not reaching customers**

<Tooltip>Likely cause</Tooltip>: the webhook business process is missing, inactive, or misconfigured.

**Fix:** verify the business process is **Active** in Creatio's Process Library. Check that the webhook URL matches the one shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Creatio. Confirm the Activity filter matches how your agents add replies. Check the process execution log in Creatio for errors. See [Case Sync — business process for agent replies](/integrations/creatio/case-sync#create-a-business-process-for-agent-replies).

### **Case closure not syncing from Creatio to OpenCX**

<Tooltip>Likely cause</Tooltip>: business process missing or inactive, or the status filter does not match exactly.

**Fix:** confirm the case closure business process is active. Verify the status filter matches your resolved/closed status name exactly (case-sensitive). Confirm the case being resolved was originally created by OpenCX — it must have a matching session for the closure to sync. See [Case Sync — business process for case closure](/integrations/creatio/case-sync#create-a-business-process-for-case-closure).

### **AI fields blank after handoff**

<Tooltip>Likely cause</Tooltip>: mapping disabled, field name mismatch, or description too vague.

**Fix:** check field mappings in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Creatio. Enable the mapping if disabled. Confirm the field name matches the exact Creatio column name (case-sensitive). Tighten the AI description with explicit values and clear criteria. See [AI Fields](/integrations/creatio/ai-fields).

### **Webhook returns an error**

<Tooltip>Likely cause</Tooltip>: webhook URL token is stale or the request body is malformed.

**Fix:**

* `401` or `Invalid token`: copy the current webhook URL from [Settings → Integrations](https://platform.open.cx/settings/integrations) → Creatio and update the business process.
* `400` or `Bad Request`: confirm the JSON body includes both `event_type` (string) and `caseId` (string). See [webhook event reference](/integrations/creatio/case-sync#webhook-event-reference).

### **None of the above**

If your issue does not match any scenario above, [contact support](mailto:support@open.cx) with:

* Your OpenCX organization name
* The session ID or Creatio case ID
* A description of what you expected vs what happened

## Limits and timing

| | Value |
| - | - |
| **Case creation** | Within seconds of handoff |
| **Activity logging** | Real time as messages are sent |
| **Webhook processing timeout** | 10 seconds |
| **AI field evaluation** | At handoff — adds a few seconds to case creation |

<Note>
  OpenCX retries on transient Creatio API failures but does not indefinitely retry past rate limits. If your Creatio instance is experiencing downtime, some events may be missed. Check Creatio's process execution logs for failed deliveries.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Creatio" icon="plug" href="/integrations/creatio/connect">
    Re-verify credentials and connection settings.
  </Card>

  <Card title="Case Sync" icon="arrows-rotate" href="/integrations/creatio/case-sync">
    Re-verify webhook business processes.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/creatio/channels/widget">
    Per-channel implementation details.
  </Card>

  <Card title="Handoff settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Azure & Dynamics Setup
Source: https://docs.open.cx/integrations/dynamics-365/azure-setup

Register an Azure AD app and wire it to a Dynamics 365 Application User so OpenCX can create incidents and live work items.

Before you paste anything into OpenCX, you need four values from Azure AD and Dynamics 365: **tenant ID**, **application (client) ID**, **client secret**, and your **environment URL**. You also need an <Tooltip>Application User</Tooltip> in Dynamics mapped to the Azure AD app and carrying a security role. Work through the steps below in order — the last step (Application User) only works after the Azure AD app exists.

## Before you start

<AccordionGroup>
  <Accordion title="Dynamics 365 with Customer Service or Omnichannel enabled" icon="check">
    OpenCX writes `incident` records, and for chat channels creates `oc_liveworkitem` records in **Omnichannel for Customer Service**. If you only plan to use phone/email handoffs, Customer Service Enterprise is enough. For web/SMS/WhatsApp handoffs, make sure Omnichannel is provisioned on the environment.
  </Accordion>

  <Accordion title="Global admin or Privileged Role Administrator in Azure AD" icon="user-shield">
    You'll register an app, create a client secret, and grant admin consent on API permissions. Any of those three steps needs tenant-level admin rights.
  </Accordion>

  <Accordion title="Power Platform admin on the target Dynamics environment" icon="user-gear">
    You'll create an Application User and assign a security role inside the Dynamics environment. Environment Admin or System Administrator on the env is enough.
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Register an app in Azure AD">
    Open the [Azure Portal → App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) and click **New registration**.

    | Field | Value |
    | - | - |
    | Name | `OpenCX Dynamics Integration` (or any name you'll recognize) |
    | Supported account types | **Accounts in this organizational directory only** (single tenant) |
    | Redirect URI | Leave blank — OpenCX uses client credentials, not interactive OAuth |

    After it's created, copy the **Directory (tenant) ID** and **Application (client) ID** from the **Overview** page.
  </Step>

  <Step title="Create a client secret">
    In the new app, go to **Certificates & secrets → Client secrets → New client secret**. Name it `opencx` and pick an expiry (24 months is the longest Azure allows).

    <Warning>
      Copy the **Value** (not the Secret ID) immediately. Azure shows it once; after you leave the page it's hidden forever and you'll need to make a new secret.
    </Warning>
  </Step>

  <Step title="Grant Dynamics API permissions">
    Go to **API permissions → Add a permission → Dynamics CRM → Delegated permissions → `user_impersonation`**. Add it, then click **Grant admin consent for `<your tenant>`**. The status column should flip to **Granted**.
  </Step>

  <Step title="Create an Application User in Dynamics">
    Open the [Power Platform admin center](https://admin.powerplatform.microsoft.com/environments) → your environment → **Settings → Users + permissions → Application users → New app user**.

    | Field | Value |
    | - | - |
    | App | Pick the Azure AD app you just registered (search by name or client ID) |
    | Business unit | The root business unit of the environment |

    Save. The Application User row now represents OpenCX inside Dynamics.
  </Step>

  <Step title="Assign a security role">
    Still on the Application User you just created, click **Manage roles** and attach a role. Two common choices:

    * **System Administrator** — simplest path; grants everything OpenCX needs and more.
    * **Custom role** — minimum privileges: `Read` on `Contact`, `Queue`, `SystemUser`; `Create` + `Write` + `Append To` on `Incident` and `Annotation`; `Create` on `Omnichannel Live Work Item` if you're using chat channels.

    Without a role, every Dynamics API call OpenCX makes returns **401 Unauthorized** even though the token exchange succeeds.
  </Step>

  <Step title="Copy your environment URL">
    Open Dynamics 365 in your browser and copy the URL up to `.dynamics.com` (example: `https://yourorg.crm.dynamics.com`). No trailing slash, no path.

    You'll use this exact string as the `scope` prefix during OAuth — a typo here will break credential verification in OpenCX.
  </Step>
</Steps>

## What you should have at the end

* **Tenant ID** (GUID from the app's **Overview** page)
* **Application (client) ID** (GUID from the same page)
* **Client secret value** (the one Azure showed once)
* **Environment URL** (e.g. `https://yourorg.crm.dynamics.com`)
* **Application User** inside Dynamics, mapped to the Azure AD app, carrying a security role

Take those four values to [Connect to OpenCX](/integrations/dynamics-365/connect) to finish wiring up the integration.

***

## Related Documentation

<CardGroup>
  <Card title="Connect to OpenCX" icon="plug" href="/integrations/dynamics-365/connect">
    Paste credentials into the OpenCX dashboard and run Test & Save.
  </Card>

  <Card title="Conversations in Dynamics 365" icon="diagram-project" href="/integrations/dynamics-365/conversations">
    Routing, incident contents, contact dedupe, and observability.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/dynamics-365/troubleshooting">
    Token 200 but verify fails, 403 on incident create, missing roles.
  </Card>

  <Card title="Dynamics 365 overview" icon="building" href="/integrations/dynamics-365/overview">
    What the integration unlocks across every channel.
  </Card>
</CardGroup>


# AI Email Support in Dynamics 365
Source: https://docs.open.cx/integrations/dynamics-365/channels/email

Create Dynamics 365 incidents from every email handoff so your reps work them from the queue they already use.

Email handoffs flow into Dynamics 365 as <Tooltip>incidents</Tooltip>. Reps work them from the Customer Service app in the queue you configure.

## Pre-requisites

<Warning>
  **Set up email forwarding into OpenCX first.** Dynamics handoff has nothing to route until emails reach OpenCX — see [Connect Email](/email/forwarding).
</Warning>

* **Email forwarding verified** — see [Connect Email](/email/forwarding).
* **Dynamics 365 credentials saved** — see [Connect to OpenCX](/integrations/dynamics-365/connect).

## How conversations land in Dynamics 365

```mermaid theme={"dark"}
flowchart LR
  A[Customer emails your address] --> B[AI answers by email]
  B --> C{AI can resolve?}
  C -- Yes --> D[Thread closes]
  C -- No --> E[Handoff triggers]
  E --> F[Incident created with transcript]
  F --> G[Rep picks up from queue]
```

## Setting up

<Steps>
  <Step title="Confirm email forwarding passes the connection test">
    In your [OpenCX dashboard](https://platform.open.cx/channels/configure/mail), the email channel status should show **Active**. If not, revisit [Connect Email](/email/forwarding).
  </Step>

  <Step title="Confirm Dynamics is connected">
    The **Dynamics 365** card on your [Settings → Integrations](https://platform.open.cx/settings/integrations) should show **Active**.
  </Step>

  <Step title="Set the default queue and priority">
    In the OpenCX Dynamics settings, set `default_queue_id` to the Dynamics queue your email team works from. Optionally set `default_owner_id` and `default_priority`.
  </Step>

  <Step title="Map any custom Dynamics fields">
    If your reps expect certain fields populated on every incident (e.g. `casetypecode`, `customerpriority`, a custom picklist), add them to `ticket_properties` as a JSON object. Use integer option-set values, not label text.
  </Step>

  <Step title="Trigger a test handoff">
    Email your forwarding address with a question the AI can't resolve. After the AI hands off, the incident appears in Dynamics in the configured queue with the transcript in the description.
  </Step>
</Steps>

## What the rep sees

* An **incident** in the Customer Service app, assigned to the queue you set.
* Title: `<classification> - <sender name or email>`.
* The full email thread rendered as the transcript inside the incident description, timestamped message by message.
* A linked contact by email — OpenCX either matches the sender's existing Dynamics contact or creates a new one.
* `Channel: email`, `Classification`, and `Sentiment` in the description header.

## Channel-specific details

<AccordionGroup>
  <Accordion title="One incident per handoff, not per email" icon="ticket">
    Every handoff creates a new incident. A single thread with multiple back-and-forth emails before handoff becomes one incident containing all those messages — reps don't see a split.
  </Accordion>

  <Accordion title="Attachments aren't copied to the incident" icon="paperclip">
    Files the customer attached to the email are visible on the OpenCX session (via the session link) but are not re-uploaded onto the Dynamics incident. Open the OpenCX session to pull the originals.
  </Accordion>

  <Accordion title="Contact dedupe by email" icon="address-card">
    OpenCX looks up `emailaddress1` before creating a contact. A repeat customer's history stays on one Dynamics contact record across multiple handoffs.
  </Accordion>

  <Accordion title="Reps reply inside Dynamics, not in OpenCX" icon="triangle-exclamation">
    Once the incident lands, the conversation continues inside Dynamics. OpenCX marks the session as handed off; messages the rep sends from Dynamics don't back-sync into the OpenCX session.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Email Support" icon="envelope" href="/email/introduction">
    Connect Email, forwarding rules, troubleshooting.
  </Card>

  <Card title="Conversations in Dynamics 365" icon="diagram-project" href="/integrations/dynamics-365/conversations">
    Incident contents, defaults, `ticket_properties`.
  </Card>

  <Card title="Connect to OpenCX" icon="plug" href="/integrations/dynamics-365/connect">
    Paste credentials and verify.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/dynamics-365/troubleshooting">
    Incidents unassigned, 403 on create, `ticket_properties` rejected.
  </Card>
</CardGroup>


# AI Phone Support in Dynamics 365
Source: https://docs.open.cx/integrations/dynamics-365/channels/phone

Hand off phone conversations from OpenCX into Dynamics 365 as incidents with the full call transcript and linked contact.

Phone handoffs flow into Dynamics 365 as <Tooltip>incidents</Tooltip>, not live work items. Reps pick the case up from the incident queue they already use — the call transcript is in the incident description.

## Pre-requisites

<Warning>
  **Configure your AI Phone number in OpenCX first.** Dynamics handoff has nothing to route until voice is live — see [Connect Phone](/phone/inbound-calls).
</Warning>

* **AI Phone number live** — see [Connect Phone](/phone/inbound-calls).
* **Dynamics 365 credentials saved** — see [Connect to OpenCX](/integrations/dynamics-365/connect).

## How conversations land in Dynamics 365

```mermaid theme={"dark"}
flowchart LR
  A[Customer calls your number] --> B[AI answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Call ends]
  C -- No --> E[Handoff triggers]
  E --> F[Incident created with transcript]
  F --> G[Rep picks up from queue]
```

## Setting up

<Steps>
  <Step title="Confirm the AI Phone number is live">
    Call your OpenCX phone number and confirm the AI answers. If not, revisit [Connect Phone](/phone/inbound-calls).
  </Step>

  <Step title="Confirm Dynamics is connected">
    The **Dynamics 365** card on your [Settings → Integrations](https://platform.open.cx/settings/integrations) should show **Active**.
  </Step>

  <Step title="Set the default queue and priority">
    In the OpenCX Dynamics integration settings, set `default_queue_id` to the Dynamics queue your voice team works from. Optionally set `default_owner_id` and `default_priority` (1–4). Without a queue or owner, incidents land unassigned and rely on Dynamics routing rules.
  </Step>

  <Step title="Trigger a test handoff">
    Call your number and ask to speak with a human. The AI hands off; the incident appears in the configured queue with the full transcript in the description.
  </Step>
</Steps>

## What the rep sees

* An **incident** in the Customer Service app, in the queue you set.
* Title formatted as `<classification> - <caller name or phone>`.
* The full call transcript in the incident description, with timestamps.
* A linked contact if the caller's email was captured by the AI during the call; otherwise the incident arrives without a linked contact.
* Tags via the description header: `Channel: phone`, `Classification: …`, `Sentiment: …`.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Transcript is posted once at handoff, not streamed" icon="clock">
    OpenCX creates the incident when the AI hands off — the description contains the conversation up to that moment. Anything said after handoff (during the live human portion of the call) is not appended to the incident.
  </Accordion>

  <Accordion title="Caller identity is phone-first" icon="address-card">
    OpenCX links the Dynamics contact by `emailaddress1`. Phone sessions usually have no email, so the incident often arrives without a linked contact. Reps can link or create one from the incident view using the caller's phone number.
  </Accordion>

  <Accordion title="Call recordings and audio don't land on the incident" icon="microphone-lines">
    The transcript is text only — the audio file is not attached to the Dynamics incident. If you need recordings, retrieve them from the OpenCX session via the session link.
  </Accordion>

  <Accordion title="Live call transfer is not done through Dynamics" icon="phone-arrow-up-right">
    When the AI hands off a call, OpenCX creates the Dynamics incident as a record of the conversation. The actual voice transfer to a human agent is handled by your OpenCX phone configuration, not Dynamics — see [Phone Agent Config](/phone/agent-config).
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Phone Support" icon="phone" href="/phone/introduction">
    Connect a number, configure voice agents.
  </Card>

  <Card title="Conversations in Dynamics 365" icon="diagram-project" href="/integrations/dynamics-365/conversations">
    Incident contents, defaults, observability.
  </Card>

  <Card title="Connect to OpenCX" icon="plug" href="/integrations/dynamics-365/connect">
    Paste credentials and verify.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/dynamics-365/troubleshooting">
    Unassigned incidents, 403 on create, missing transcript.
  </Card>
</CardGroup>


# AI SMS Support in Dynamics 365
Source: https://docs.open.cx/integrations/dynamics-365/channels/sms

Route inbound SMS conversations from OpenCX into Dynamics 365 Omnichannel for Customer Service as live work items.

SMS handoffs flow through <Tooltip>Omnichannel for Customer Service</Tooltip> as `oc_liveworkitem` records. Reps handle them as chats in the **Omnichannel Agent** app, not as incidents.

## Pre-requisites

<Warning>
  **Connect SMS in OpenCX first.** Dynamics handoff has nothing to route until an SMS number is live — see [Connect SMS](/sms/connect-sms).
</Warning>

* **SMS number connected** — see [Connect SMS](/sms/connect-sms).
* **Dynamics 365 credentials saved** — see [Connect to OpenCX](/integrations/dynamics-365/connect).

## How conversations land in Dynamics 365

```mermaid theme={"dark"}
flowchart LR
  A[Customer texts your number] --> B[AI answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation closes]
  C -- No --> E[Handoff triggers]
  E --> F[oc_liveworkitem created]
  F --> G[Rep picks up in Omnichannel Agent]
```

## Setting up

<Steps>
  <Step title="Confirm the SMS number is live">
    Text your OpenCX SMS number and confirm the AI responds. If not, revisit [Connect SMS](/sms/connect-sms).
  </Step>

  <Step title="Confirm Dynamics is connected">
    The **Dynamics 365** card on your [Settings → Integrations](https://platform.open.cx/settings/integrations) should show **Active**.
  </Step>

  <Step title="Point the workstream to your SMS rep queue">
    Copy the workstream GUID from **Omnichannel admin center → Workstreams** for the team that should handle SMS, and paste it into `default_queue_id` in the OpenCX Dynamics settings.
  </Step>

  <Step title="Trigger a test handoff">
    Text your SMS number with *"Can I talk to an agent?"*. The live work item should arrive in the **Omnichannel Agent** app.
  </Step>
</Steps>

## What the rep sees

* A **live SMS chat** in the Omnichannel Agent app — not an incident.
* The AI's session summary as the conversation subject.
* `sessionId` and `channel: sms` in the work item's context variables.
* The customer's phone number on the work item (email is usually empty for SMS sessions).
* OpenCX records `dynamics365_chat_id` on the OpenCX session for audit.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Contact lookup is email-first — SMS sessions land without a linked contact by default" icon="address-card">
    OpenCX looks up `emailaddress1` when linking a contact. SMS sessions usually have no email, so the live work item often arrives unlinked. Collect an email in the AI flow before handoff if you want contact linkage on the Dynamics side.
  </Accordion>

  <Accordion title="US numbers require 10DLC or toll-free registration" icon="flag">
    If your SMS number is in the US, carriers enforce **10DLC** or toll-free verification before delivery. This is an OpenCX-side requirement — see [SMS Compliance](/sms/compliance). Dynamics doesn't replace the need.
  </Accordion>

  <Accordion title="Segment length and MMS" icon="message">
    Long SMS messages get split into 160-character segments (70 for non-GSM). MMS (images, longer text) is supported on US long codes and toll-free but not all short codes — confirm your number type.
  </Accordion>

  <Accordion title="Rep replies in Omnichannel don't sync back to OpenCX today" icon="triangle-exclamation">
    Reps continue the conversation inside Dynamics. Messages they send don't back-sync into the OpenCX session.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI SMS Support" icon="comment-sms" href="/sms/introduction">
    Connect a number, configure the AI agent.
  </Card>

  <Card title="SMS Compliance" icon="flag" href="/sms/compliance">
    10DLC and toll-free registration for US numbers.
  </Card>

  <Card title="Conversations in Dynamics 365" icon="diagram-project" href="/integrations/dynamics-365/conversations">
    Routing rules, live work item payload, observability.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/dynamics-365/troubleshooting">
    Live work item never appears, unlinked contact on SMS.
  </Card>
</CardGroup>


# AI WhatsApp Support in Dynamics 365
Source: https://docs.open.cx/integrations/dynamics-365/channels/whatsapp

Route WhatsApp Business conversations from OpenCX into Dynamics 365 Omnichannel for Customer Service as live work items.

WhatsApp handoffs flow through <Tooltip>Omnichannel for Customer Service</Tooltip> as `oc_liveworkitem` records. Reps handle them as chats in the **Omnichannel Agent** app, not as incidents.

## Pre-requisites

<Warning>
  **Connect WhatsApp in OpenCX first.** Dynamics handoff has nothing to route until a WhatsApp number is live — see [Connect WhatsApp](/whatsapp/connect-whatsapp).
</Warning>

* **WhatsApp number connected** — see [Connect WhatsApp](/whatsapp/connect-whatsapp).
* **Dynamics 365 credentials saved** — see [Connect to OpenCX](/integrations/dynamics-365/connect).

## How conversations land in Dynamics 365

```mermaid theme={"dark"}
flowchart LR
  A[Customer messages WhatsApp] --> B[AI answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation closes]
  C -- No --> E[Handoff triggers]
  E --> F[oc_liveworkitem created]
  F --> G[Rep picks up in Omnichannel Agent]
```

## Setting up

<Steps>
  <Step title="Confirm the WhatsApp number is live">
    Send a test message to your WhatsApp number and confirm the AI responds. If not, revisit [Connect WhatsApp](/whatsapp/connect-whatsapp).
  </Step>

  <Step title="Confirm Dynamics is connected">
    The **Dynamics 365** card on your [Settings → Integrations](https://platform.open.cx/settings/integrations) should show **Active**.
  </Step>

  <Step title="Point the workstream to your WhatsApp rep queue">
    Copy the workstream GUID from **Omnichannel admin center → Workstreams** for the rep team that should handle WhatsApp, and paste it into `default_queue_id` in the OpenCX Dynamics settings. For this WhatsApp handoff flow, `default_queue_id` is a legacy/shared setting name and should contain the **Omnichannel workstream GUID** used to route `oc_liveworkitem` chats — not an incident queue GUID. Other Dynamics 365 docs may use the same field name for incident-style routing, so if you're configuring cases/incidents rather than Omnichannel live chat, follow that flow's queue-specific instructions instead.
  </Step>

  <Step title="Trigger a test handoff">
    Message your WhatsApp number with *"I need a human"*. The AI hands off; the live work item appears in the **Omnichannel Agent** app tied to the routing rules on the workstream you set.
  </Step>
</Steps>

## What the rep sees

* A **live WhatsApp chat** in the Omnichannel Agent app — not an incident.
* The AI's session summary as the conversation subject.
* `sessionId` and `channel: whatsapp` in the work item's context variables.
* The customer's WhatsApp phone number on the work item (email may be empty).
* OpenCX records `dynamics365_chat_id` on the OpenCX session for audit.

## Channel-specific details

<AccordionGroup>
  <Accordion title="24-hour WhatsApp session window" icon="clock">
    WhatsApp's Business API only allows reps to send free-form messages within 24 hours of the customer's last inbound message. After that window, outbound messages must use approved templates. Omnichannel honors this restriction — reps will see a template picker outside the window.
  </Accordion>

  <Accordion title="Contact lookup is email-first, so WhatsApp contacts may be unlinked" icon="address-card">
    OpenCX links contacts by `emailaddress1`. WhatsApp sessions often have no email, so the live work item may arrive without a linked contact. Reps can link one from the conversation view — or collect an email in the AI flow before handoff.
  </Accordion>

  <Accordion title="Media attachments" icon="paperclip">
    Images, audio, and documents the customer sends in WhatsApp attach to the Omnichannel conversation thread. Meta's WhatsApp media size limits apply (typically 16 MB).
  </Accordion>

  <Accordion title="Rep replies in Omnichannel don't sync back to OpenCX today" icon="triangle-exclamation">
    Reps continue the conversation inside Dynamics. Messages they send don't back-sync into the OpenCX session; OpenCX marks the session as handed off once the live work item is created.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI WhatsApp Support" icon="whatsapp" href="/whatsapp/introduction">
    Connect a number, configure the AI agent.
  </Card>

  <Card title="Conversations in Dynamics 365" icon="diagram-project" href="/integrations/dynamics-365/conversations">
    Routing rules, live work item payload, observability.
  </Card>

  <Card title="Connect to OpenCX" icon="plug" href="/integrations/dynamics-365/connect">
    Paste credentials and verify.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/dynamics-365/troubleshooting">
    Live work item never appears, template window issues.
  </Card>
</CardGroup>


# AI Chat Widget in Dynamics 365
Source: https://docs.open.cx/integrations/dynamics-365/channels/widget

Route web chat conversations from the AI Chat Widget into Dynamics 365 Omnichannel for Customer Service as live work items.

Widget conversations hand off as <Tooltip>Omnichannel live work items</Tooltip>, not incidents. When the AI hands off a chat, your rep picks it up as a real-time chat inside the **Omnichannel Agent** app — no case opened, no ticket queue.

## Pre-requisites

<Warning>
  **Install the AI Chat Widget on your site first.** Dynamics handoff has nothing to route until the widget is live — start with [Install Widget](/widget/install-widget) and come back here.
</Warning>

* **Widget installed and reachable** — see [Install Widget](/widget/install-widget).
* **Dynamics 365 credentials saved** — see [Connect to OpenCX](/integrations/dynamics-365/connect).

## How conversations land in Dynamics 365

```mermaid theme={"dark"}
flowchart LR
  A[Visitor opens widget] --> B[AI answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Visitor closes chat]
  C -- No --> E[Handoff triggers]
  E --> F[oc_liveworkitem created]
  F --> G[Rep picks up in Omnichannel Agent]
```

## Setting up

<Steps>
  <Step title="Confirm the widget is live">
    Open the page where the widget is embedded and send a test message. You should see the AI respond. If not, walk through [Install Widget](/widget/install-widget) first.
  </Step>

  <Step title="Confirm Dynamics is connected">
    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), the **Dynamics 365** card should show **Active**. If it doesn't, re-run Test & Save in [Connect to OpenCX](/integrations/dynamics-365/connect).
  </Step>

  <Step title="Set a default workstream (optional but recommended)">
    The Omnichannel live work item routes to the workstream you pass as `workstreamId`. OpenCX uses your `default_queue_id` setting for that. Copy the workstream GUID from **Omnichannel admin center → Workstreams** and paste it into `default_queue_id` in the OpenCX Dynamics settings.
  </Step>

  <Step title="Trigger a test handoff">
    Say *"I want to talk to a human"* in the widget. The AI should hand off. Open the **Omnichannel Agent** app and accept the incoming chat.
  </Step>
</Steps>

<Tip>
  If the handoff lands as an **incident** instead of a live work item, the session's `channel` isn't `web`. See the troubleshooting scenario on routing below.
</Tip>

## What the rep sees

* A **live chat in the Omnichannel Agent app**, not a case in the Customer Service app.
* The AI's session summary as the **conversation subject**.
* `sessionId` and `channel: web` in the work item's <Tooltip>context variables</Tooltip> — `sessionId` is the trace key back to OpenCX.
* Customer name, email, and phone pre-filled on the work item from the session.
* OpenCX records `dynamics365_chat_id` on the OpenCX session for audit.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Omnichannel routing rules apply on the Dynamics side" icon="route">
    OpenCX creates the `oc_liveworkitem` with a `workstreamId`; Dynamics's **Workstream → Routing rules → Assignment method** decide which queue and which rep picks it up. Align `default_queue_id` with a workstream that has routing rules you actually want.
  </Accordion>

  <Accordion title="Anonymous vs authenticated widget visitors" icon="shield-check">
    When the widget passes a verified email via [widget authentication](/widget/authentication), OpenCX links the existing Dynamics contact on that email. Anonymous visitors land with no contact linked on the work item — reps can link one manually.
  </Accordion>

  <Accordion title="Widget custom components still render on the visitor side" icon="bolt">
    When an AI action returns data rendered by a [custom component](/widget/custom-components), the visitor sees the richer UI. The rep in Omnichannel Agent sees the underlying text — write copy that reads well in both surfaces.
  </Accordion>

  <Accordion title="Rep replies in Omnichannel don't sync back to the widget today" icon="triangle-exclamation">
    Reps should continue the conversation inside the Omnichannel Agent app. OpenCX marks the session as handed off once the live work item is created; messages the rep sends in Dynamics stay in Dynamics.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Chat Widget" icon="messages" href="/widget/introduction">
    Install, configure, authenticate the widget itself.
  </Card>

  <Card title="Conversations in Dynamics 365" icon="diagram-project" href="/integrations/dynamics-365/conversations">
    Routing rules, live work item payload, observability.
  </Card>

  <Card title="Connect to OpenCX" icon="plug" href="/integrations/dynamics-365/connect">
    Paste credentials and verify the connection.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/dynamics-365/troubleshooting">
    Live work item never appears, handoff lands as incident instead.
  </Card>
</CardGroup>


# Connect to OpenCX
Source: https://docs.open.cx/integrations/dynamics-365/connect

Paste Azure AD credentials into the OpenCX dashboard and verify the connection to Dynamics 365.

With the four values from [Azure & Dynamics Setup](/integrations/dynamics-365/azure-setup) in hand, pasting them into OpenCX takes about a minute. **Test & Save Configuration** runs a round-trip against Dynamics to confirm the credentials work before the row is saved.

<Warning>
  **Complete [Azure & Dynamics Setup](/integrations/dynamics-365/azure-setup) first.** Without an Application User on the Dynamics side, Test & Save will fail — the Azure token returns 200 but the Dynamics API call returns 401.
</Warning>

## Paste the credentials

<Steps>
  <Step title="Open the Dynamics 365 integration modal">
    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), find the **Dynamics 365** card and click **Configure**.
  </Step>

  <Step title="Fill in the four fields">
    | Field | Where it comes from |
    | - | - |
    | **Client ID** | Azure app registration → Overview → Application (client) ID |
    | **Client Secret** | The value you copied when you created the secret (not the Secret ID) |
    | **Tenant ID** | Azure app registration → Overview → Directory (tenant) ID |
    | **Environment URL** | `https://yourorg.crm.dynamics.com` (no trailing slash) |
  </Step>

  <Step title="Click Test & Save Configuration">
    OpenCX runs the verification described below. On success you'll see a confirmation toast and the card flips to **Active**. On failure the save is rejected and nothing is written to the database.
  </Step>
</Steps>

## What "Test & Save" does

<Info>
  Verification is two calls, not one. Both must succeed for the credentials to save.
</Info>

* **Token exchange** — OpenCX POSTs to `https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token` with `grant_type=client_credentials` and `scope=<environment_url>/.default`. A 400 here means Azure AD rejected the tenant/client/secret triple.
* **Dynamics probe** — OpenCX uses the token to `GET <environment_url>/api/data/v9.2/incidents`. A 401 or 403 here means the token is fine but the Application User or its security role isn't.
* **Save** — Only after both calls return 2xx does OpenCX upsert the row into `dynamics365_integration_settings` (encrypted at rest).

## Rotating the client secret

Azure AD client secrets expire. A few days before the expiry:

1. Create a new secret in the same app registration (**Certificates & secrets → New client secret**).
2. Copy the new value.
3. Open the OpenCX Dynamics 365 modal, paste the new secret, and click **Test & Save Configuration**.
4. Delete the old secret in Azure once you've confirmed the new one works.

You don't need to change the tenant ID, client ID, or environment URL — they don't rotate.

## Disconnecting

Opening the modal and removing the settings row deletes the credentials from OpenCX. Incidents and Omnichannel live work items that were already created stay in Dynamics exactly as they are — disconnecting only stops OpenCX from creating new ones.

***

## Related Documentation

<CardGroup>
  <Card title="Conversations in Dynamics 365" icon="diagram-project" href="/integrations/dynamics-365/conversations">
    Routing logic, contact dedupe, defaults, and observability.
  </Card>

  <Card title="AI Chat Widget in Dynamics 365" icon="comments" href="/integrations/dynamics-365/channels/widget">
    First channel to try — widget handoff lands as an Omnichannel live work item.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/dynamics-365/troubleshooting">
    Credential verify fails, unassigned incidents, unlinked contacts.
  </Card>

  <Card title="Azure & Dynamics Setup" icon="microsoft" href="/integrations/dynamics-365/azure-setup">
    App registration, secret, Application User, security role.
  </Card>
</CardGroup>


# Conversations in Dynamics 365
Source: https://docs.open.cx/integrations/dynamics-365/conversations

How OpenCX routes handoffs into Dynamics 365 incidents or Omnichannel live work items, what gets written, and how to trace it back.

Every handoff to Dynamics 365 takes one of two paths: a real-time **live work item** in Omnichannel for Customer Service, or a **case incident** in the core Customer Service app. OpenCX picks the path automatically from the OpenCX channel.

## How handoff routes

```mermaid theme={"dark"}
flowchart LR
  A[OpenCX session hands off] --> B{Channel}
  B -- web / sms / whatsapp --> C[Omnichannel live work item]
  B -- phone / email / other --> D[Incident + linked contact]
```

The routing rule is fixed: `web`, `sms`, and `whatsapp` flow into Omnichannel; everything else flows into an incident. You can't override it per session — the channel of the OpenCX session decides.

## Incident contents

When a handoff lands as an incident, OpenCX writes these fields on the `incident` record:

* **`title`** — `<classification> - <customer name or email>` (falls back to `Support - Anonymous` if neither is set).
* **`description`** — header lines for `Channel`, `Summary`, `Classification`, `Sentiment`, **Customer Details** (name, email, phone), followed by the full AI-to-customer transcript with timestamps.
* **`prioritycode`** — the `default_priority` you set in settings (1–4). Defaults to `2` (Medium).
* **`customerid_contact@odata.bind`** — the linked contact (see below).
* **`ownerid@odata.bind`** — the `default_owner_id` you set, if any.
* **`queueid@odata.bind`** — the `default_queue_id` you set, if any.
* **Your `ticket_properties`** — any extra Dynamics fields you want populated, spread onto the payload as-is.

## Contact handling

OpenCX keeps one Dynamics contact per customer email:

* **Lookup** — OpenCX queries `contacts?$filter=emailaddress1 eq '<email>'`. If a match comes back, OpenCX links the incident to that contact.
* **Create** — If no match, OpenCX creates a new contact with `firstname`/`lastname` split from the session name, `emailaddress1`, `mobilephone` from the session, and `description: Created from chat session <session_id>`.
* **No email** — If the session has no email at all (anonymous widget visitor, SMS-only session with no captured email), the incident is created **without a linked contact**. Reps can link one manually after the fact.

## Defaults you can set per org

These live in the Dynamics integration row and are applied on every incident:

| Setting | Type | Effect |
| - | - | - |
| `default_priority` | integer 1–4 | Written as `prioritycode`. Defaults to `2` (Medium). |
| `default_owner_id` | Systemuser GUID | Written as `/systemusers(<id>)`. Leave blank to let Dynamics routing rules assign. |
| `default_queue_id` | Queue GUID | Written as `/queues(<id>)`. Leave blank to skip queue assignment. |
| `ticket_properties` | JSON object | Merged into the incident payload. Use integer codes for option sets, and full `/entity(guid)` paths for any additional `@odata.bind` fields. |

Incidents already exist in Dynamics — OpenCX doesn't invent new fields. Every key in `ticket_properties` must be a real column or lookup the Application User can write.

## Omnichannel live work items

For web, SMS, and WhatsApp handoffs, OpenCX POSTs an `oc_liveworkitem` with:

* `name` and `customerInfo.name` — the session name (or `Anonymous`).
* `email` / `customerInfo.email` — the session email, if any.
* `subject` — the AI's session summary.
* `workstreamId` — your `default_queue_id` from settings (used as the workstream).
* `contextVariables` — `sessionId` and `channel`, so the Omnichannel routing rules on your side can branch on them.

The returned `oc_liveworkitemid` is stored as `dynamics365_chat_id` on the OpenCX session.

## Observability fields

| Surface | Field | Value |
| - | - | - |
| OpenCX session `meta` | `dynamics365_incident_id` | Incident GUID (case handoffs) |
| OpenCX session `meta` | `dynamics365_ticket_number` | Human-readable ticket number Dynamics auto-generates |
| OpenCX session `meta` | `dynamics365_chat_id` | `oc_liveworkitemid` (chat handoffs) |
| OpenCX session `meta` | `dynamics365_chat_status` | `initiated` once the live work item posts |
| Dynamics contact | `emailaddress1` | Customer email — the trace key for dedupe |
| Dynamics incident | `description` header | `Channel`, `Classification`, `Sentiment` — reps filter on these |

Search either `dynamics365_incident_id` or `dynamics365_ticket_number` in Dynamics advanced find to jump to the record from an OpenCX session.

## Closing the case

When the OpenCX session resolves, OpenCX PATCHes the incident with `statecode: 1` (Resolved) and `statuscode: 5` (Problem Solved). Reps can reopen the incident from Dynamics — OpenCX does not prevent it.

***

## Related Documentation

<CardGroup>
  <Card title="Connect to OpenCX" icon="plug" href="/integrations/dynamics-365/connect">
    Paste credentials and run Test & Save.
  </Card>

  <Card title="AI Chat Widget in Dynamics 365" icon="comments" href="/integrations/dynamics-365/channels/widget">
    Web chat → Omnichannel live work item.
  </Card>

  <Card title="AI Email Support in Dynamics 365" icon="envelope" href="/integrations/dynamics-365/channels/email">
    Email → Incident with transcript and linked contact.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/dynamics-365/troubleshooting">
    Routing lands on the wrong entity, unassigned incidents, 403 on create.
  </Card>
</CardGroup>


# Dynamics 365 overview
Source: https://docs.open.cx/integrations/dynamics-365/overview

Hand off AI conversations into Microsoft Dynamics 365 as incidents or Omnichannel live work items your reps already work.

OpenCX connects to **Microsoft Dynamics 365 Customer Service** so handoffs land where your reps already work. Chat channels (web, SMS, WhatsApp) flow into <Tooltip>Omnichannel for Customer Service</Tooltip> as live work items; phone and email flow into Dynamics as <Tooltip>incidents</Tooltip>. Either way the rep sees the full AI transcript, channel, sentiment, and a linked contact.

<Tip>
  Start with [Azure & Dynamics Setup](/integrations/dynamics-365/azure-setup), then paste credentials in your [OpenCX dashboard](https://platform.open.cx/settings/integrations).
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="Incidents your reps already work" icon="ticket">
    Phone and email handoffs create a Dynamics incident with the full transcript, channel, classification, sentiment, and a linked contact. Reps pick up from the queue they already use — no separate inbox.
  </Accordion>

  <Accordion title="Omnichannel live work items for chat" icon="comments">
    Web, SMS, and WhatsApp handoffs create an `oc_liveworkitem` so reps handle them as live chats inside the Omnichannel Agent app, not as incidents.
  </Accordion>

  <Accordion title="Contacts linked by email" icon="address-card">
    OpenCX looks up the customer by `emailaddress1`. If the contact exists it's linked on the record; if not, OpenCX creates one with the name, email, and phone from the session.
  </Accordion>

  <Accordion title="Custom field passthrough" icon="sliders">
    Map a `ticket_properties` JSON object in your integration settings to write extra Dynamics fields (priority codes, case type, custom attributes) on every incident OpenCX creates.
  </Accordion>
</AccordionGroup>

## Supported channels

<CardGroup>
  <Card title="AI Chat Widget" icon="comments" href="/integrations/dynamics-365/channels/widget">
    Web chat handed off as an Omnichannel live work item.
  </Card>

  <Card title="AI WhatsApp Support" icon="whatsapp" href="/integrations/dynamics-365/channels/whatsapp">
    WhatsApp handed off as an Omnichannel live work item.
  </Card>

  <Card title="AI SMS Support" icon="comment-sms" href="/integrations/dynamics-365/channels/sms">
    SMS handed off as an Omnichannel live work item.
  </Card>

  <Card title="AI Phone Support" icon="phone" href="/integrations/dynamics-365/channels/phone">
    Call transcript handed off as a Dynamics incident.
  </Card>

  <Card title="AI Email Support" icon="envelope" href="/integrations/dynamics-365/channels/email">
    Email thread handed off as a Dynamics incident.
  </Card>
</CardGroup>

## Observability

Every conversation OpenCX hands to Dynamics 365 is traceable from either side.

<AccordionGroup>
  <Accordion title="Incident reference on every case handoff" icon="fingerprint">
    OpenCX stores `dynamics365_incident_id` (the Dataverse GUID) and `dynamics365_ticket_number` (the human-readable number Dynamics generates) on the OpenCX session. Search either value in Dynamics advanced find to jump straight to the record.
  </Accordion>

  <Accordion title="Work item reference on every chat handoff" icon="messages">
    For web, SMS, and WhatsApp handoffs, OpenCX stores `dynamics365_chat_id` (the `oc_liveworkitemid`) on the session. That's the identifier the Omnichannel Agent app routes on.
  </Accordion>

  <Accordion title="Contact dedupe by email" icon="address-card">
    OpenCX looks up `emailaddress1` before creating a contact, so a returning customer's records stay on the same Dynamics contact row. Reps see one history, not a fork.
  </Accordion>

  <Accordion title="Channel, classification, sentiment in the incident body" icon="tag">
    The incident description header contains `Channel:`, `Classification:`, and `Sentiment:` lines. Reps filter and search on those without leaving Dynamics.
  </Accordion>
</AccordionGroup>

## Pick your setup path

<CardGroup>
  <Card title="Azure & Dynamics Setup, then Connect" icon="microsoft" href="/integrations/dynamics-365/azure-setup">
    Register an Azure AD app, create the Application User, assign a security role, then paste credentials into OpenCX. One linear flow.
  </Card>
</CardGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Azure & Dynamics Setup" icon="microsoft" href="/integrations/dynamics-365/azure-setup">
    App registration, client secret, Application User, security role.
  </Card>

  <Card title="Conversations in Dynamics 365" icon="diagram-project" href="/integrations/dynamics-365/conversations">
    How handoff routes, what's written on the record, defaults you can set.
  </Card>

  <Card title="AI Chat Widget in Dynamics 365" icon="comments" href="/integrations/dynamics-365/channels/widget">
    First channel to wire up — widget → Omnichannel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/dynamics-365/troubleshooting">
    Credential verify failures, missing queues, unlinked contacts.
  </Card>
</CardGroup>


# Dynamics 365 troubleshooting
Source: https://docs.open.cx/integrations/dynamics-365/troubleshooting

Debug Dynamics 365 credential verification, incident creation, Omnichannel routing, and contact linking issues.

Before debugging, have this ready:

* The **Azure tenant ID**, **client ID**, and **environment URL** you used to save the integration.
* A specific <Tooltip>session ID</Tooltip> (from [Inbox](https://platform.open.cx/inbox)) or a Dynamics incident/ticket number where the problem shows.
* Admin access to both **Azure AD** and the **Power Platform admin center**.

<Tip>
  Re-run **Test & Save Configuration** in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Dynamics 365 as your first step. It runs the token exchange plus a `GET /incidents` probe and tells you which half is failing.
</Tip>

<Info>
  **Fastest path to root cause:** open the failing OpenCX session and check `meta` for `dynamics365_incident_id` (or `dynamics365_chat_id`). If the field exists, the record was created in Dynamics — the problem is on the Dynamics side (assignment, routing). If not, the handoff itself failed — scope to credentials or the routing rule.
</Info>

## Common scenarios

Jump to the symptom that matches what you're seeing.

### **"Failed to verify credentials" on save**

<Tooltip>Likely cause</Tooltip>: wrong tenant ID, expired secret, or missing admin consent.

**Fix:** paste the **Directory (tenant) ID** from the Azure app's **Overview** page (not the object ID, not the application ID). Regenerate the client secret in **Certificates & secrets** if yours is past its expiry. In **API permissions**, confirm `Dynamics CRM → user_impersonation` is added **and** shows **Granted for `<tenant>`**.

### **Test & Save fails even though the client secret is brand new**

<Tooltip>Likely cause</Tooltip>: environment URL typo or trailing slash.

**Fix:** paste the URL exactly as shown in your browser up to `.dynamics.com` — no path, no trailing slash. Example: `https://yourorg.crm.dynamics.com`.

### **Token exchange succeeds, but the Dynamics probe returns 401**

<Tooltip>Likely cause</Tooltip>: <Tooltip>Application User</Tooltip> not created, or not mapped to the Azure AD app.

**Fix:** open the [Power Platform admin center](https://admin.powerplatform.microsoft.com/environments) → your env → **Settings → Users + permissions → Application users**. Confirm there's a row for your Azure AD app (search by client ID). If not, create one. See [Azure & Dynamics Setup, step 4](/integrations/dynamics-365/azure-setup).

### **Token exchange succeeds, Dynamics probe returns 403**

<Tooltip>Likely cause</Tooltip>: Application User has no security role, or the role lacks Incident privileges.

**Fix:** on the Application User row, click **Manage roles** and attach one. **System Administrator** is the simplest path; for a least-privilege setup give the role `Read` on Contact/Queue/SystemUser and `Create + Write + Append To` on Incident and Annotation. If you're using chat channels, add `Create` on Omnichannel Live Work Item.

### **Incident created but unassigned**

<Tooltip>Likely cause</Tooltip>: `default_owner_id` and `default_queue_id` both blank, and no Dynamics routing rule catches the record.

**Fix:** set `default_queue_id` in the OpenCX Dynamics settings to the queue your reps work from, and optionally `default_owner_id` for a specific systemuser. Either one (or a Dynamics routing rule) has to claim the incident for it to show up in a rep's view.

### **Incident created but not in the expected queue**

<Tooltip>Likely cause</Tooltip>: security role missing `Append To` on the queue.

**Fix:** in Dynamics, open the security role attached to the Application User and tick `Append To` on **Queue** at the required scope (usually Business Unit).

### **Contact not linked on the incident**

<Tooltip>Likely cause</Tooltip>: session has no email.

**Fix:** gate handoff behind user-data collection so the AI captures an email before routing to Dynamics (in the widget, set `collectUserData: true` — see [widget configuration](/widget/configuration)). For SMS/phone, collect the email in-flow. Reps can also link a contact manually after the fact from the incident view.

### **Chat handoff from web/SMS/WhatsApp lands as an incident instead of Omnichannel**

<Tooltip>Likely cause</Tooltip>: the session's `channel` value isn't one of `web`, `sms`, or `whatsapp`.

**Fix:** check the OpenCX session's `channel` field. If you're dispatching through a custom integration, confirm it sets one of the three supported strings; anything else routes to the incident path by design.

### **Omnichannel live work item never appears in the Agent app**

<Tooltip>Likely cause</Tooltip>: Omnichannel isn't provisioned, or the workstream bound to `default_queue_id` has no routing rules.

**Fix:** confirm **Omnichannel for Customer Service** is enabled on your environment from the Power Platform admin center. Open **Omnichannel admin center → Workstreams**, pick the workstream matching your `default_queue_id`, and verify it has **Routing rules** that route live work items to queues.

### **`ticket_properties` values rejected on incident create**

<Tooltip>Likely cause</Tooltip>: option-set labels used instead of codes, or lookup written as a raw GUID.

**Fix:** use integer codes for option sets (e.g. `"prioritycode": 1` for High, not `"High"`). For lookup fields, use the `@odata.bind` form, e.g. `"customerid_account@odata.bind": "/accounts(<guid>)"`. Check the Dataverse schema for the entity if unsure.

### **`POST /incidents` returns 403 at handoff time**

<Tooltip>Likely cause</Tooltip>: role lacks `Create` privilege on Incident.

**Fix:** in Dynamics, open the security role → **Service** tab → find **Case** (the Incident entity) → ensure **Create** is set at the right scope (usually Business Unit or Organization).

### **Rep replies in Dynamics don't appear in the OpenCX session**

<Tooltip>Likely cause</Tooltip>: back-sync isn't implemented.

**Fix:** none — the current integration is one-way. Reps continue the conversation inside Dynamics; OpenCX marks the session as handed off once the record is created. If you need a two-way audit trail, link to the OpenCX session from the incident description.

## Limits & timing

| Item | Limit | Notes |
| - | - | - |
| Access token | Fetched per request | No token cache or refresh layer today — each handoff exchanges a fresh token. |
| OAuth scope | `{environment_url}/.default` | Must match the saved environment URL exactly, including protocol. |
| Dataverse API version | `v9.2` | OpenCX pins this version for every call. |
| Incident body length | Dynamics-side limit | Very long transcripts can hit the Dataverse string-field cap; older Dynamics versions limit descriptions around 100k characters. |
| Retry behavior | None | A transient Azure AD or Dynamics 5xx is not retried; the handoff surfaces the error. Re-trigger the handoff to retry. |

***

## Related Documentation

<CardGroup>
  <Card title="Azure & Dynamics Setup" icon="microsoft" href="/integrations/dynamics-365/azure-setup">
    Re-check app registration, Application User, and security role.
  </Card>

  <Card title="Connect to OpenCX" icon="plug" href="/integrations/dynamics-365/connect">
    Re-run Test & Save after fixing credentials or roles.
  </Card>

  <Card title="Conversations in Dynamics 365" icon="diagram-project" href="/integrations/dynamics-365/conversations">
    Routing rules, defaults, observability.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    When OpenCX decides to hand off in the first place.
  </Card>
</CardGroup>


# Booking Flow
Source: https://docs.open.cx/integrations/fareharbor/booking-flow

How the AI uses FareHarbor actions to list tours, check availability, validate pricing, and complete bookings.

Once FareHarbor is [connected](/integrations/fareharbor/connect), your AI agent follows a structured flow to move customers from interest to confirmed reservation.

## Booking lifecycle

```mermaid theme={"dark"}
flowchart LR
    A[List tours] --> B[Check availability]
    B --> C[Validate pricing]
    C --> D{Payment link}
    C --> E{Direct booking}
    D --> F[Customer pays]
    E --> G[Booking confirmed]
    F --> G
```

The AI walks through these steps automatically based on the conversation. It will not skip ahead — availability is always checked before validation, and validation is always checked before booking.

## AI actions

Each action below maps to a toggle in the FareHarbor settings. Disable any action to prevent the AI from using it.

<AccordionGroup>
  <Accordion title="List Tours & Activities" icon="list">
    The AI retrieves all bookable items for the configured company. Each item includes a name, headline, and per-ticket pricing. This is usually the first action the AI calls when a customer asks what is available.
  </Accordion>

  <Accordion title="Check Availability" icon="calendar">
    Given a specific tour and date, the AI looks up open time slots. Each slot includes the start time, remaining capacity, and per-ticket-type pricing. The availability and customer type rate identifiers returned here are required for all subsequent booking steps.
  </Accordion>

  <Accordion title="Validate Booking" icon="circle-check">
    Before committing a booking, the AI confirms the selected time slot is still available and retrieves the exact price breakdown (subtotal, taxes, total). This guards against stale availability — a slot that was open seconds ago may have filled.
  </Accordion>

  <Accordion title="Create Booking" icon="check-to-slot">
    Confirms a reservation directly through the FareHarbor API. Requires the customer's name, email, and phone number. FareHarbor sends a confirmation email to the customer automatically.

    <Warning>
      Create Booking is **disabled by default**. It creates a confirmed reservation without collecting payment through FareHarbor's checkout. Enable it only if your payment workflow is handled separately.
    </Warning>
  </Accordion>

  <Accordion title="Get Booking" icon="magnifying-glass">
    Looks up an existing booking by its UUID. Returns the current status (booked, cancelled, rebooked), confirmation details, and whether the booking is still eligible for cancellation.
  </Accordion>

  <Accordion title="Cancel Booking" icon="ban">
    Cancels an existing booking by its UUID. FareHarbor applies a grace period after creation — the AI checks `is_eligible_for_cancellation` before attempting to cancel.
  </Accordion>

  <Accordion title="Get Payment Link" icon="link">
    Generates a FareHarbor payment link the customer can open to review their booking details and complete payment. This is the **recommended booking path** — the customer handles payment on FareHarbor's hosted checkout rather than providing card details in the conversation.
  </Accordion>

  <Accordion title="Send Payment Link via SMS" icon="comment-sms">
    Sends the payment link to the customer's phone number via SMS. The AI composes a short, friendly message in the customer's language and appends the payment link automatically. Useful during voice calls where the customer cannot click a link.
  </Accordion>
</AccordionGroup>

## Managing AI actions

Control exactly which actions your AI agent can perform from the FareHarbor settings in your [OpenCX dashboard](https://platform.open.cx/settings/integrations).

| Action | Default | What it controls |
| - | - | - |
| List Tours & Activities | On | AI can show customers what is available |
| Check Availability | On | AI can look up open time slots for a date |
| Validate Booking | On | AI can confirm pricing before committing |
| Create Booking | **Off** | AI can complete a reservation directly |
| Get Booking | On | AI can look up existing bookings |
| Cancel Booking | On | AI can cancel a booking on behalf of the customer |
| Get Payment Link | On | AI can generate a self-service payment URL |
| Send Payment Link via SMS | On | AI can text the payment link to the customer |

## Payment links

Payment links are the recommended way to handle bookings. When the AI generates a payment link:

1. The customer receives a URL pointing to FareHarbor's hosted checkout.
2. The checkout page shows the selected tour, time slot, pricing, and a payment form.
3. The customer completes payment directly on FareHarbor — no card details pass through OpenCX.
4. FareHarbor sends the confirmation email.

The AI can share the link inline in a chat message or send it via SMS during a voice call.

## Good to know

<AccordionGroup>
  <Accordion title="Company resolution" icon="building">
    If you selected a default company during setup, the AI uses that company for all bookings without asking the customer. If you chose Auto-detect, the AI resolves the company from your affiliated companies list. When multiple companies are affiliated, the AI may ask the customer which company they mean.
  </Accordion>

  <Accordion title="Connection resolution (multi-location orgs)" icon="layer-group">
    If you have more than one FareHarbor connection configured, every tool call includes a `location` parameter identifying which connection to use. The AI resolves this automatically whenever the customer's request matches a specific connection (for example, the customer names a brand, region, or company that maps to one connection). If the request is ambiguous, the AI asks which location or brand the customer means before proceeding.

    Per-action toggles apply to **each connection independently** — you can allow bookings on one connection while keeping another read-only.
  </Accordion>

  <Accordion title="Pricing format" icon="dollar-sign">
    FareHarbor returns prices in cents. The AI converts to dollar format (e.g. \$45.00) before presenting to customers. Tax breakdowns are shown when the AI validates a booking.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Connect FareHarbor" icon="plug" href="/integrations/fareharbor/connect">
    API keys, sandbox mode, and Test & Connect.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/fareharbor/troubleshooting">
    Connection failures, missing availability, SMS issues.
  </Card>

  <Card title="Chat" icon="comments" href="/integrations/fareharbor/channels/chat">
    How booking conversations work in chat.
  </Card>

  <Card title="Voice" icon="phone" href="/integrations/fareharbor/channels/voice">
    How booking conversations work on calls.
  </Card>
</CardGroup>


# Chat in FareHarbor
Source: https://docs.open.cx/integrations/fareharbor/channels/chat

How FareHarbor booking conversations work in the AI chat widget, WhatsApp, and SMS channels.

<Warning>
  Before using FareHarbor in chat, make sure your [chat agent is set up](/widget/introduction) and [FareHarbor is connected](/integrations/fareharbor/connect).
</Warning>

## How booking conversations work in chat

When a customer starts a booking conversation in any text-based channel — web widget, WhatsApp, or SMS — the AI follows the same structured flow.

```mermaid theme={"dark"}
flowchart LR
    A[Customer message] --> B[AI lists matching tours]
    B --> C[AI checks availability]
    C --> D[AI shares options and pricing]
    D --> E[Customer picks a slot]
    E --> F[AI sends payment link]
```

The AI adapts to the customer's language automatically. A customer writing in Spanish receives tour names, prices, and the payment link message in Spanish.

## What the customer sees

1. **Tour options** — The AI presents available tours with names, short descriptions, and per-ticket prices as formatted text.
2. **Time slots** — After the customer picks a tour, the AI shows open dates and times with remaining capacity.
3. **Pricing confirmation** — The AI validates the selected slot and presents the exact total including taxes.
4. **Payment link** — A clickable URL the customer opens to complete their booking on FareHarbor's hosted checkout. In chat, the link renders inline as a tappable URL.

If the Create Booking action is enabled, the AI may confirm the reservation directly after collecting the customer's name, email, and phone number — without generating a payment link.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Works across all text channels" icon="grid-2">
    The FareHarbor booking tools are available on every text-based channel your AI agent operates on: web chat widget, WhatsApp, and SMS. The booking experience is identical — the only difference is how the payment link renders (tappable URL in all cases).
  </Accordion>

  <Accordion title="Payment links are clickable" icon="link">
    In chat, the AI shares the payment link as a standard URL. Customers tap or click to open FareHarbor's checkout page in their browser. No copy-pasting required.
  </Accordion>

  <Accordion title="Multi-language support" icon="globe">
    The AI detects the customer's language from the conversation and responds in the same language. Tour names and descriptions come from FareHarbor as configured by the operator — the AI translates its own messages (availability summaries, pricing confirmations, the payment link message) but not FareHarbor content.
  </Accordion>

  <Accordion title="Multiple companies" icon="building">
    If your FareHarbor account is affiliated with multiple companies and no default is set, the AI asks the customer which company they want to book with before listing tours. If a default company is configured, the AI uses it without asking.
  </Accordion>

  <Accordion title="Multiple FareHarbor connections" icon="layer-group">
    If your organization has more than one FareHarbor connection (for example, different locations or currency accounts), the AI picks the right connection automatically when the customer's request is specific enough to match one. For general requests, the AI asks the customer which location or brand they are interested in before listing tours. Each connection has its own AI action toggles, so capabilities can differ per location.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Chat Widget" icon="comments" href="/widget/introduction">
    Set up your chat agent before adding FareHarbor.
  </Card>

  <Card title="Connect FareHarbor" icon="plug" href="/integrations/fareharbor/connect">
    API keys, sandbox mode, and Test & Connect.
  </Card>

  <Card title="Overview" icon="anchor" href="/integrations/fareharbor/overview">
    Capabilities and supported channels.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/fareharbor/troubleshooting">
    Connection failures, missing availability, SMS issues.
  </Card>
</CardGroup>


# Voice in FareHarbor
Source: https://docs.open.cx/integrations/fareharbor/channels/voice

How FareHarbor booking conversations work on voice calls, with SMS payment link delivery.

<Warning>
  Before using FareHarbor on voice, make sure your [voice agent is set up](/phone/create-agent) and [FareHarbor is connected](/integrations/fareharbor/connect).
</Warning>

## How booking conversations work on calls

When a customer calls and asks about booking a tour or activity, the AI follows the same structured booking flow — adapted for a spoken conversation.

```mermaid theme={"dark"}
flowchart LR
    A[Customer speaks] --> B[AI reads tour options]
    B --> C[AI checks availability]
    C --> D[AI speaks pricing]
    D --> E[Customer confirms]
    E --> F[AI sends payment link via SMS]
```

The AI speaks naturally — reading tour names, available times, and prices aloud — and asks clarifying questions when needed ("Which date would you like?" or "How many adults?").

## What the customer hears

1. **Tour options** — The AI reads available tours by name with headline descriptions and per-ticket prices.
2. **Time slots** — After the customer picks a tour, the AI reads open dates, times, and remaining spots.
3. **Pricing confirmation** — The AI confirms the total including taxes before proceeding.
4. **SMS with payment link** — Since the customer cannot tap a link during a call, the AI sends a text message containing the payment link to the customer's phone number.

If the Create Booking action is enabled, the AI may confirm the reservation verbally after collecting the customer's name, email, and phone number.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Payment links delivered via SMS" icon="comment-sms">
    During a voice call, the customer cannot click a link. The AI uses the **Send Payment Link via SMS** action to text the FareHarbor checkout link to the customer's phone. The SMS includes a short, friendly message composed by the AI in the customer's language, with the payment link appended.
  </Accordion>

  <Accordion title="Phone number collection" icon="phone">
    If the customer's phone number is already known from caller ID, the AI uses it for SMS delivery without asking. If the number is not available, the AI asks the customer for their phone number before sending the payment link.
  </Accordion>

  <Accordion title="Direct booking on call" icon="check-to-slot">
    When the Create Booking action is enabled, the AI can confirm a reservation during the call itself. It collects the customer's name, email, and phone number verbally, then creates the booking. FareHarbor sends a confirmation email to the customer.
  </Accordion>

  <Accordion title="Multiple FareHarbor connections" icon="layer-group">
    If your organization has more than one FareHarbor connection (for example, different locations or currency accounts), the AI picks the right one automatically based on the customer's request. If a customer names a brand, region, or tour that maps clearly to one connection, no extra prompt is needed. If the request is ambiguous, the AI asks the customer which location they mean before looking up tours.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Phone Support" icon="phone" href="/phone/create-agent">
    Set up your voice agent before adding FareHarbor.
  </Card>

  <Card title="Connect FareHarbor" icon="plug" href="/integrations/fareharbor/connect">
    API keys, sandbox mode, and Test & Connect.
  </Card>

  <Card title="Overview" icon="anchor" href="/integrations/fareharbor/overview">
    Capabilities and supported channels.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/fareharbor/troubleshooting">
    Connection failures, missing availability, SMS issues.
  </Card>
</CardGroup>


# Connect FareHarbor
Source: https://docs.open.cx/integrations/fareharbor/connect

Add one or more FareHarbor connections, validate your keys, and configure per-connection AI actions.

<FareharborFlow />

<Info>
  OpenCX supports **multiple FareHarbor connections per organization** — one per location, brand, or currency account. Each connection has its own API keys and its own AI action toggles.
</Info>

## Prerequisites

<AccordionGroup>
  <Accordion title="FareHarbor API partner account" icon="key">
    You need an **App Key** and a **User Key** issued by FareHarbor. These authenticate every request OpenCX makes to the FareHarbor API on your behalf. Contact FareHarbor to register as an API partner if you do not already have keys.
  </Accordion>

  <Accordion title="Currency-matched User Key" icon="dollar-sign">
    If you work with FareHarbor companies in different currencies (USD, NZD, EUR, etc.), you will have a separate **User Key for each currency**. Add one connection per currency — the AI will route each booking to the right connection automatically.
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Open the FareHarbor add-on">
    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), go to **Settings → Add-ons** and select **FareHarbor**.
  </Step>

  <Step title="Add a connection">
    Click **Add Connection**. If you already have connections configured, they are listed here — you can add more by clicking the button again.
  </Step>

  <Step title="Give the connection a name">
    Enter a **connection name** that reflects what this connection is — for example `Downtown Location`, `USD Account`, or `RealNZ`. The name is what your AI agent uses to disambiguate between connections during customer conversations, so pick something meaningful.

    <Tip>
      Pick names your **customers** would recognize, not internal codes. If a customer asks about a specific brand or region, the AI can match the request to the right connection without asking.
    </Tip>
  </Step>

  <Step title="Choose your environment">
    Toggle **Sandbox Mode** on for testing. This points the connection at FareHarbor's demo environment — no real bookings, no real charges.
  </Step>

  <Step title="Enter your API keys">
    Paste your **App Key** and **User Key**. OpenCX validates both keys immediately by calling the FareHarbor API to list your affiliated companies. If validation fails, double-check that the keys are correct and that the User Key matches the currency of at least one affiliated company.
  </Step>

  <Step title="Select a default company">
    After key validation succeeds, a dropdown appears with the companies affiliated with this User Key. Pick the company you want this connection to book for. If there is only one, it is selected automatically.

    You can also leave this as **Auto-detect** — the AI will use the first company returned by the FareHarbor API for this connection.
  </Step>

  <Step title="Click Test & Connect">
    OpenCX runs a final validation and saves the connection. The new connection appears in the list and is ready to use immediately.
  </Step>
</Steps>

## Managing connections

Each connection has its own settings panel, reached by clicking it in the connection list:

* **AI actions** — eight toggleable capabilities (list items, check availability, validate booking, create booking, get booking, cancel booking, generate payment link, send payment link via SMS). Each connection has its own toggles, so you can allow bookings on one location while keeping another read-only.
* **Disconnect** — removes just that connection. Other connections remain active.

## How the AI picks the right connection

When you have more than one connection, every FareHarbor tool call the AI makes includes a **location** parameter — which connection to use. The AI resolves this automatically whenever it can:

* If the customer mentions a specific company, tour, or region that maps to one connection, the AI uses it without asking.
* If the request is ambiguous (e.g. "what tours do you have?"), the AI asks the customer which location or brand they are interested in.

With a **single connection**, there is no `location` parameter and no disambiguation — behavior is identical to a single-connection setup.

## Disconnecting

To remove a single connection, open it from the connection list and click **Disconnect**. This removes:

* The stored API keys for that connection
* The AI action settings for that connection

Other connections, and your FareHarbor account itself, are not affected.

***

## Related Documentation

<CardGroup>
  <Card title="Troubleshooting" icon="wrench" href="/integrations/fareharbor/troubleshooting">
    Connection failures, missing availability, SMS delivery.
  </Card>

  <Card title="Booking Flow" icon="route" href="/integrations/fareharbor/booking-flow">
    How each AI action works day-to-day.
  </Card>

  <Card title="Overview" icon="anchor" href="/integrations/fareharbor/overview">
    Capabilities, supported channels, and how it all fits together.
  </Card>

  <Card title="Chat" icon="comments" href="/integrations/fareharbor/channels/chat">
    Booking experience in chat widget, WhatsApp, and SMS.
  </Card>
</CardGroup>


# Fareharbor overview
Source: https://docs.open.cx/integrations/fareharbor/overview

Let your AI agent book tours, activities, and experiences for customers through FareHarbor — on chat or voice.

OpenCX connects to your <Tooltip>FareHarbor</Tooltip> account so your AI agent can browse tours, check availability, validate pricing, and complete bookings — all inside the conversation your customer is already in. No separate booking portal, no context switch.

<Tip>
  Setup starts at [**Settings → Add-ons**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="AI books tours and activities automatically" icon="calendar-check">
    Your customers describe what they want — "dolphin tour next Saturday for two adults" — and the AI handles the rest: finds matching items, checks open time slots, confirms pricing, and either creates the booking or sends a payment link. The customer never leaves the conversation.
  </Accordion>

  <Accordion title="Payment links customers complete on their own" icon="credit-card">
    The recommended booking path generates a FareHarbor payment link the customer can open to review details and pay. The AI can share the link in chat or send it via SMS during a voice call.
  </Accordion>

  <Accordion title="Sandbox mode for safe testing" icon="flask">
    Toggle sandbox mode to point at FareHarbor's demo environment. Test the full booking flow — listing, availability, validation, creation — without creating real reservations or charging real cards.
  </Accordion>

  <Accordion title="Full booking lifecycle" icon="arrows-rotate">
    The AI can list items, check availability, validate pricing, create bookings, look up existing reservations, and cancel within the grace period. Each capability maps to a toggleable action you control from the dashboard.
  </Accordion>

  <Accordion title="Per-action control from the dashboard" icon="sliders">
    Enable or disable individual AI actions — for example, allow availability checks and payment links but block direct booking creation. Your team decides exactly what the AI can do.
  </Accordion>

  <Accordion title="Multiple locations, brands, or currencies" icon="layer-group">
    Connect more than one FareHarbor account to the same organization. Each connection has its own API keys, its own default company, and its own AI action toggles. The AI picks the right connection automatically based on the customer's request, and only asks if the intent is ambiguous.
  </Accordion>
</AccordionGroup>

## Supported channels

The FareHarbor integration works across every channel your AI agent operates on. Pick a channel below for implementation details specific to that surface.

<CardGroup>
  <Card title="Chat" icon="comments" href="/integrations/fareharbor/channels/chat">
    Booking conversations in web widget, WhatsApp, and SMS.
  </Card>

  <Card title="Voice" icon="phone" href="/integrations/fareharbor/channels/voice">
    Booking conversations on phone calls with SMS payment delivery.
  </Card>
</CardGroup>

## How a booking conversation flows

```mermaid theme={"dark"}
flowchart LR
    A[Customer asks] --> B[AI lists tours]
    B --> C[AI checks availability]
    C --> D[AI validates pricing]
    D --> E{Payment link or direct booking}
    E --> F[Customer completes payment]
    E --> G[AI creates booking]
    F --> H[Confirmation]
    G --> H
```

***

## Related Documentation

<CardGroup>
  <Card title="Connect FareHarbor" icon="plug" href="/integrations/fareharbor/connect">
    API keys, sandbox mode, company selection, and Test & Connect.
  </Card>

  <Card title="Booking Flow" icon="route" href="/integrations/fareharbor/booking-flow">
    How each AI action works and when payment links are used.
  </Card>

  <Card title="Chat" icon="comments" href="/integrations/fareharbor/channels/chat">
    Booking experience in chat widget, WhatsApp, and SMS.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/fareharbor/troubleshooting">
    Connection failures, missing availability, SMS delivery.
  </Card>
</CardGroup>


# Fareharbor troubleshooting
Source: https://docs.open.cx/integrations/fareharbor/troubleshooting

Fix connection failures, missing availability, booking errors, and SMS delivery issues with the FareHarbor integration.

Have your App Key, User Key, and the [OpenCX inbox](https://platform.open.cx/inbox) open before you start.

<Tip>
  If you recently changed your FareHarbor API keys, [reconnect the integration](/integrations/fareharbor/connect) to re-validate.
</Tip>

## Common issues

| Symptom | Likely cause | Fix |
| - | - | - |
| **Test & Connect fails** | Invalid App Key or User Key; User Key currency does not match any affiliated company; sandbox mode toggled incorrectly | Double-check both keys in FareHarbor's partner portal. Confirm the User Key currency matches the company you expect. If testing, make sure sandbox mode is on. |
| **AI does not offer booking options** | FareHarbor not connected; all actions disabled; no items returned for the configured company | Verify the integration is connected in **Settings → Add-ons**. Check that at least List Tours and Check Availability are enabled. Confirm the default company has published bookable items in FareHarbor. |
| **No availability returned for a date** | No open slots on that date; the company has no availability configured for the selected item; date format mismatch | Check the FareHarbor dashboard for the company's availability calendar. The AI sends dates in YYYY-MM-DD format — verify the item actually has slots published for the requested date. |
| **AI asks the customer which location when it shouldn't have to** | Connection names are too generic (e.g. "Account 1", "Test"); customer's request doesn't clearly map to a connection | Rename each connection to something customers would recognize (a brand, region, or company name). Set a `default_company_shortname` so the AI can match tour and company mentions to the right connection. |
| **Payment link SMS not delivered** | Customer phone number not in international format; SMS delivery failure | The phone number must include the country code (e.g. +1 for US, +64 for NZ). Verify the number is correct and reachable. If the number is correct but SMS still fails, contact support. |
| **None of the above** | — | Contact [OpenCX support](mailto:support@open.cx) with your organization name and a description of the issue. Include the session ID from the inbox if available. |

<Info>
  Most connection issues come from mismatched keys or currency. If Test & Connect fails, the error message from FareHarbor's API is shown in the dashboard — read it carefully before retrying.
</Info>

## Booking-specific issues

If the AI connects and lists tours but bookings fail or behave unexpectedly, check these items:

* **Create Booking is disabled by default.** The AI cannot confirm reservations unless you explicitly enable the Create Booking action in FareHarbor settings. This is intentional — most teams use payment links instead.
* **Cancellation has a grace period.** FareHarbor allows cancellations only within a short window after creation. The AI checks `is_eligible_for_cancellation` before attempting to cancel. If the grace period has passed, the booking cannot be cancelled through the AI.
* **Always validate before creating.** The AI validates availability and pricing before every booking attempt, but if the time slot fills between validation and creation, the booking will fail. The AI handles this by informing the customer and asking them to pick a different slot.
* **Sandbox bookings are not real.** When sandbox mode is on, all bookings are created in FareHarbor's demo environment. They will not appear in your production FareHarbor dashboard and no confirmation emails are sent to real addresses.

## Limits

| Limit | Value |
| - | - |
| Connections per organization | Unlimited (one per location/brand/currency) |
| Connection name | Unique within the organization |
| Default company per connection | 1 (or Auto-detect) |
| AI actions | 8 toggleable actions, per connection |
| Payment link SMS | Requires international phone format |

***

## Related Documentation

<CardGroup>
  <Card title="Connect FareHarbor" icon="plug" href="/integrations/fareharbor/connect">
    Re-verify your keys and sandbox setting.
  </Card>

  <Card title="Booking Flow" icon="route" href="/integrations/fareharbor/booking-flow">
    How each AI action works day-to-day.
  </Card>

  <Card title="Overview" icon="anchor" href="/integrations/fareharbor/overview">
    Capabilities and supported channels.
  </Card>

  <Card title="Voice" icon="phone" href="/integrations/fareharbor/channels/voice">
    SMS payment link delivery during voice calls.
  </Card>
</CardGroup>


# Connect Freshchat
Source: https://docs.open.cx/integrations/freshchat/connect

Generate a Freshchat API token, enter your credentials in OpenCX, register the webhook in Freshchat, and pick a routing mode.

The Freshchat integration uses a <Tooltip>Freshchat API access token</Tooltip> to read and write conversations in your workspace, plus a webhook you register in Freshchat that pushes events back to OpenCX.

<FreshchatFlow />

<Info>
  Setup takes about 10 minutes. You need admin access in both Freshchat and your
  OpenCX organization.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Admin access in Freshchat" icon="user-shield">
    Only Freshchat admins can generate API tokens and register webhooks. Agent roles cannot reach the **Admin Settings → Integrations & APIs** page.
  </Accordion>

  <Accordion title="Pick the default agent" icon="user-headset">
    The AI posts replies in Freshchat as an agent you designate. Customers see
    that agent's name and avatar on every AI message, so create a dedicated agent
    (for example *OpenCX AI*) rather than reusing a person's account. The agent
    must exist in Freshchat before setup — OpenCX resolves it by email.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="key">
    Required to save integration settings in [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Generate a Freshchat API access token">
    In Freshchat, open **Admin Settings → Integrations & APIs** and create a new API token.

    1. Label it `OpenCX` (or anything recognizable).
    2. Make sure the token has conversation management permissions.
    3. **Copy the token immediately** — Freshchat hides it after you close the dialog.

    See [Freshchat's API documentation](https://support.freshchat.com/en/support/solutions/articles/50000000306-freshchat-apis) for the latest path if Freshchat moves it.

    <Warning>
      The token is bound to the admin that created it. If that admin is deactivated or loses permissions, the integration stops working.
    </Warning>
  </Step>

  <Step title="Open Freshchat in OpenCX">
    In your OpenCX dashboard, go to [**Settings →
    Integrations**](https://platform.open.cx/settings/integrations) and select
    **FreshChat**.
  </Step>

  <Step title="Enter your credentials">
    | Field | Value |
    | - | - |
    | **Domain** | Your Freshchat workspace domain — for example `yourcompany.freshchat.com`. Include the full domain, do not prefix with `https://`. |
    | **Access Token** | The API token you just copied. |
    | **Default Agent Email** | The email of the Freshchat <Tooltip>default agent</Tooltip> the AI posts as. The agent must already exist in Freshchat. |

    Click **Test & Save**. OpenCX calls the Freshchat API with your credentials before saving — a wrong domain or bad token returns an error and nothing persists.

    <Warning>
      The agent email is **not** checked at save time — OpenCX resolves it later, when it first assigns or replies. A typo here fails silently, so double-check the email matches the agent in Freshchat exactly.
    </Warning>
  </Step>

  <Step title="Pick a routing mode">
    The **Auto Handle All Incoming Chats** toggle controls which conversations the AI picks up.

    <AccordionGroup>
      <Accordion title="Auto-handle all incoming chats (toggle on)" icon="bolt">
        The AI claims every unassigned Freshchat conversation by assigning it to the default agent, then replies. Use this when the AI is the front door to your chat support.
      </Accordion>

      <Accordion title="Assigned-only (toggle off)" icon="filter">
        The AI only replies to conversations Freshchat has already assigned to the default agent email. Use this when your existing Freshchat routing rules decide which chats go to the AI — for example, business-hours routing or team-based assignment.
      </Accordion>
    </AccordionGroup>

    You can change modes anytime. New conversations follow the current setting; in-flight conversations keep their current assignment.
  </Step>

  <Step title="Choose the handoff strategy">
    Choose what OpenCX should do in Freshchat after the AI hands off to a human.

    | Strategy | What happens | When to use it |
    | - | - | - |
    | **Unassign conversation** | OpenCX removes the AI/default agent from the conversation. | Use this when your team works from the unassigned queue or manually triages handoffs. |
    | **Freshchat automation** | OpenCX sets the handoff marker property, then your Freshchat assignment rules route the conversation. | Use this when routing should stay inside Freshchat rules, queues, or automations. |
    | **Assign to another Freshchat agent** | OpenCX assigns the conversation directly to the **Handoff Agent Email** you enter. | Use this for a fixed fallback agent or small teams without routing automation. |
    | **Assign to a Freshchat support group** | OpenCX sets the handoff marker, then moves the conversation into the **Handoff Group** you pick. | Use this when a team queue should receive handoffs, but Freshchat automation rules are not needed. |

    Picking a strategy reveals its configuration field:

    * **Assign to another Freshchat agent** — enter the **Handoff Agent Email** of the human agent who receives handoffs. It must be a different agent from the default (AI) agent email.
    * **Assign to a Freshchat support group** — pick the **Handoff Group** from the dropdown, loaded live from your Freshchat workspace.

    <Info>
      Group handoffs land with status **new**, not assigned — so if the group uses <Tooltip>IntelliAssign</Tooltip>, Freshchat still picks the agent within the group. OpenCX routes to the queue; Freshchat routes to the person.
    </Info>

    For the marker-based strategies — **Freshchat automation** and **Assign to a Freshchat support group** — create a checkbox conversation property in Freshchat (the agent-assignment strategy doesn't need it):

    | Field | Value |
    | - | - |
    | **Label** | `OpenCX handed off` |
    | **Internal/API name** | `cf_opencx_handed_off` |
    | **Type** | Checkbox |

    <Warning>
      Some Freshchat roles can view conversation properties but cannot create or edit them. If you cannot add the `cf_opencx_handed_off` property, ask a Freshchat admin to create it, or select an existing editable custom checkbox property that your routing rules can safely use as the handoff marker.
    </Warning>

    If you use Freshchat automation or support group handoff, update your Freshchat rules so conversations with the marker set are **not** routed back to the OpenCX/default AI agent.
  </Step>

  <Step title="Copy your webhook URL">
    After saving, OpenCX displays a **Webhook URL** unique to your organization. Keep this tab open — you'll paste it into Freshchat in the next step.

    <Warning>
      The webhook URL contains a signed token tied to your organization. Anyone with it can post events into your OpenCX pipeline. Treat it like a password.
    </Warning>
  </Step>

  <Step title="Register the webhook in Freshchat">
    In Freshchat, open **Admin Settings → Integrations & APIs → Webhooks** and add a new webhook.

    | Field | Value |
    | - | - |
    | **Endpoint URL** | Paste the OpenCX webhook URL. |
    | **Events to subscribe** | **Message Create**, **Conversation Assignment**, **Conversation Resolution**, **Conversation Reopen**. |

    <Warning>
      Each unchecked event breaks a specific flow: without **Message Create** the AI never sees customer messages; without **Conversation Assignment** the assigned-only routing mode never wakes the AI; without **Conversation Resolution** closures in Freshchat don't sync back to OpenCX; without **Conversation Reopen** reopened chats stay closed in OpenCX.
    </Warning>

    Save the webhook.
  </Step>

  <Step title="Send a test message">
    Open your Freshchat widget as an end user and send a message. Within a few seconds:

    1. A new session appears in your [OpenCX Inbox](https://platform.open.cx/inbox) under the **Web** channel.
    2. The AI's reply appears in the Freshchat conversation as the default agent.

    <Info>
      **The session back-links to Freshchat.** Open the session from your inbox — the Freshchat conversation URL is stored on it so you can jump straight back into Freshchat to audit the rep view.
    </Info>

    If the session doesn't appear, jump to [Troubleshooting](/integrations/freshchat/troubleshooting).
  </Step>
</Steps>

## Rotating the API token

Freshchat tokens are long-lived but admins sometimes rotate them for compliance. To rotate:

1. Generate a new token in **Admin Settings → Integrations & APIs**.
2. Paste it into [Settings → Integrations → FreshChat](https://platform.open.cx/settings/integrations) and click **Test & Save**.
3. Revoke the old token in Freshchat.

The webhook URL does not change when you rotate the token — the webhook is signed with a separate key tied to your organization.

## Disconnecting

In OpenCX, open the Freshchat integration and click **Disconnect**. Then in Freshchat, delete the webhook you created. Conversations already exchanged stay in your OpenCX inbox; no new Freshchat messages flow in, and the AI stops posting in Freshchat.

***

## Related Documentation

<CardGroup>
  <Card title="Conversation flow" icon="diagram-project" href="/integrations/freshchat/conversations">
    How inbound messages match to sessions, how handoff routes the chat, how
    resolutions sync.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/freshchat/troubleshooting">
    Credentials failing, webhook silent, handoff note missing.
  </Card>

  <Card title="Overview" icon="comment" href="/integrations/freshchat/overview">
    What the Freshchat integration does and how it fits with your team.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Conversation flow
Source: https://docs.open.cx/integrations/freshchat/conversations

How Freshchat conversations reach the AI, how handoff routes the chat with a private note, and how resolutions sync both ways.

After setup, every Freshchat conversation that matches your routing mode flows through OpenCX. The AI replies inline as your default agent, hands off when it can't resolve, and closes conversations when it can.

## How a chat lands on the AI

```mermaid theme={"dark"}
flowchart LR
  A[Customer message in Freshchat] --> B[Freshchat webhook]
  B --> C[OpenCX matches conversation]
  C --> D[AI replies as default agent]
```

The match step is the load-bearing one. OpenCX uses the Freshchat conversation ID to decide whether to append to an existing session or open a new one — the session back-links to the Freshchat thread so your reps can jump straight into Freshchat from the [OpenCX Inbox](https://platform.open.cx/inbox).

## Routing modes

The **Auto Handle All Incoming Chats** toggle on the [FreshChat integration settings](https://platform.open.cx/settings/integrations) picks which conversations the AI answers. See [Connect Freshchat](/integrations/freshchat/connect) for setup.

* **Auto-handle all incoming chats** — the AI claims every unassigned Freshchat conversation and replies.
* **Assigned-only** — the AI only replies to conversations Freshchat has already assigned to the default agent email.

## When the AI hands off

<Steps>
  <Step title="The AI decides it cannot resolve">
    Handoff triggers follow your global handoff rules — topics not in the Autopilot allowlist, explicit customer asks for a human, confidence thresholds, office-hours rules.
  </Step>

  <Step title="OpenCX routes the Freshchat conversation">
    OpenCX applies your configured handoff strategy. The default `unassign`
    strategy sets the conversation back to **new**, removes the default agent, and
    keeps the current group so Freshchat routing or your reps' unassigned queue
    can pick it up. Other strategies can mark the conversation for Freshchat
    automation, assign it directly to a configured human agent, or move it into a
    Freshchat support group. Group handoffs arrive with status **new** so
    IntelliAssign can still pick the agent within the group — see [Connect
    Freshchat](/integrations/freshchat/connect) for strategy setup.
  </Step>

  <Step title="A private handoff note lands on the Freshchat conversation">
    OpenCX posts a private note containing the AI summary and detected sentiment. The note is Freshchat-internal — your customer never sees it.

    <Info>
      Your rep reads the summary before typing. The note is the primary handoff-to-rep observability surface; there is no separate OpenCX link inside Freshchat today.
    </Info>
  </Step>

  <Step title="Your rep picks up the conversation">
    Your rep replies in Freshchat as normal. OpenCX marks the OpenCX session as handed off so the AI stops auto-replying. Rep replies from Freshchat are not ingested as new customer messages.
  </Step>
</Steps>

## When the AI resolves

<Steps>
  <Step title="The AI session auto-resolves">
    OpenCX's auto-resolution logic closes the session when the conversation is complete — for example, after a successful answer with no further customer response.
  </Step>

  <Step title="OpenCX resolves the Freshchat conversation">
    The Freshchat conversation status moves to **resolved** and a private resolution note is posted with the summary and sentiment. Your reporting picks up the resolution on both sides.
  </Step>
</Steps>

## When a rep closes in Freshchat

When a rep resolves the conversation directly in Freshchat, the **Conversation Resolution** webhook event flows back to OpenCX and closes the matching session as **resolved**. If the conversation is later reopened in Freshchat, the **Conversation Reopen** event reopens the session. If these events are not subscribed in your Freshchat webhook, sessions drift out of sync — see [Troubleshooting](/integrations/freshchat/troubleshooting).

## Channel-specific details

<AccordionGroup>
  <Accordion title="One contact per email, even across Freshchat users" icon="users">
    OpenCX maps contacts by email. If two Freshchat users share the same email, the second conversation links to the first user's contact in OpenCX — history stays on one record. This is by design to keep customer histories merged. If you need separate contacts, use distinct emails in Freshchat.
  </Accordion>

  <Accordion title="Rep replies sync to OpenCX without waking the AI" icon="reply">
    When a rep types in Freshchat after handoff, OpenCX records the reply on the
    session timeline — public replies as agent messages, private notes as internal
    comments — including any attachments. The reply is never treated as a new
    customer message, so the AI stays silent on handed-off conversations.
  </Accordion>

  <Accordion title="Attachments flow through, both directions" icon="paperclip">
    Inbound, images and files sent through Freshchat message parts land on the
    matching OpenCX session — from customers and from your reps — so the AI and
    your inbox see them alongside text. Outbound, when the AI's answer contains an
    image, OpenCX renders it as a native inline image in Freshchat rather than a
    bare link.
  </Accordion>

  <Accordion title="Anonymous visitors are backfilled when they identify" icon="user-plus">
    If a Freshchat visitor starts anonymous and later shares an email, name, or
    phone, OpenCX backfills those details onto the contact. If another contact
    already owns that email, the session re-links to the existing contact so
    history stays on one record.
  </Accordion>

  <Accordion title="Channel and group names become session tags" icon="tags">
    OpenCX tags each session with the Freshchat conversation's channel and group
    names, so inbox filters and reports can segment by where the chat came from
    and which team owns it.
  </Accordion>

  <Accordion title="Very long messages" icon="align-left">
    OpenCX does not truncate outbound messages before sending them to Freshchat.
    Freshchat itself may reject messages that exceed its per-message size limit
    without an error surfaced to you — keep replies within typical chat lengths.
  </Accordion>

  <Accordion title="Duplicate webhook deliveries" icon="rotate-right">
    Freshchat sometimes re-delivers the same webhook. OpenCX ignores repeated deliveries of the same message (content, attachments, and timestamp) for 24 hours, so retries do not produce double replies or duplicate sessions.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Troubleshooting" icon="wrench" href="/integrations/freshchat/troubleshooting">
    AI not replying, handoff note missing, conversations not closing.
  </Card>

  <Card title="Connect Freshchat" icon="plug" href="/integrations/freshchat/connect">
    Re-verify credentials, webhook events, and routing mode.
  </Card>

  <Card title="Overview" icon="comment" href="/integrations/freshchat/overview">
    What the Freshchat integration does and how it fits with your team.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Freshchat overview
Source: https://docs.open.cx/integrations/freshchat/overview

Run Freshchat as the surface your agents work in while OpenCX answers, escalates, and keeps conversation status in sync.

OpenCX works alongside your team inside Freshchat. The AI resolves what it can on the same live conversation your customer is already writing to, escalates cleanly when automation stops, and writes an AI-drafted private note on every handoff so your rep picks up with full context — no separate inbox, no copy-paste.

<Tip>
  Setup starts at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="AI replies on your live Freshchat conversations" icon="robot">
    When a customer writes in through your Freshchat widget, OpenCX receives the message, matches it to an existing conversation or opens a new one, and the AI posts its reply in Freshchat as the agent you designate. To your customer, the AI and your team look like the same surface. <Tooltip href="/handoff/topics">Autopilot</Tooltip> controls which topics the AI will answer versus escalate.
  </Accordion>

  <Accordion title="Handoff preserves the thread" icon="user-group">
    When the AI escalates, OpenCX routes the Freshchat conversation according to your configured handoff strategy and posts a private <Tooltip href="/handoff/introduction">handoff</Tooltip> note containing the AI's summary and detected sentiment. The note is visible to your reps in Freshchat only — the customer never sees it. Your rep reads the summary and replies on the same thread.
  </Accordion>

  <Accordion title="Two ways to route chats to the AI" icon="route">
    Pick whichever fits your routing rules — no middle ground:

    * **Auto-handle all incoming chats** — the AI claims every unassigned Freshchat conversation. Use this when the AI is the front door.
    * **Assigned-only** — the AI only answers conversations your Freshchat rules have already assigned to the default agent email. Use this when your existing routing decides which chats go to the AI.
  </Accordion>

  <Accordion title="Status stays in sync both ways" icon="rotate">
    When the AI auto-resolves, OpenCX sets the Freshchat conversation to **resolved** and posts a private resolution note with the summary and sentiment. When a rep closes or resolves the conversation in Freshchat, OpenCX closes the matching session as resolved. Your reporting keeps the same denominator on both sides.
  </Accordion>
</AccordionGroup>

## Observability

Every Freshchat conversation the AI touches is traceable from OpenCX back to the Freshchat thread — and back from Freshchat through the private note the AI wrote.

<AccordionGroup>
  <Accordion title="Back-link to the Freshchat conversation from every session" icon="link">
    The OpenCX session stores the Freshchat conversation URL. Open the session from your [OpenCX Inbox](https://platform.open.cx/inbox) and jump straight to the exact Freshchat thread — no conversation-ID lookup required.
  </Accordion>

  <Accordion title="AI summary visible inside Freshchat" icon="note-sticky">
    Every handoff and every AI resolution drops a private note into the Freshchat conversation. The note contains the AI summary, detected sentiment, and the reason the AI stopped auto-replying. Your reps read it in the Freshchat UI before they type a word.
  </Accordion>

  <Accordion title="Identity mapping by email" icon="fingerprint">
    OpenCX maps one contact per Freshchat user using the email your customer shared in Freshchat. If two Freshchat users share an email, OpenCX links the new conversation to the existing contact so your history stays on one record — expected behavior, not a merge bug.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Freshchat" icon="plug" href="/integrations/freshchat/connect">
    Generate an API token, paste your credentials, register the webhook in Freshchat.
  </Card>

  <Card title="Conversation flow" icon="diagram-project" href="/integrations/freshchat/conversations">
    How messages reach the AI, how handoff lands, how resolutions sync.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/freshchat/troubleshooting">
    AI not replying, handoff note missing, conversations not closing.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Freshchat troubleshooting
Source: https://docs.open.cx/integrations/freshchat/troubleshooting

Debug Freshchat credentials, webhook events, routing mode, handoff notes, and resolution sync.

Before debugging, have this ready:

* Your Freshchat <Tooltip>domain</Tooltip> and the admin email that owns the <Tooltip>API token</Tooltip>.
* A specific OpenCX session ID (from [Inbox](https://platform.open.cx/inbox)) or Freshchat conversation ID where the problem shows.
* The **Default Agent Email** you saved in the integration settings.

<Tip>
  Re-run **Test & Save** in [Settings →
  Integrations](https://platform.open.cx/settings/integrations) → FreshChat as
  your first step. Most issues are credential or webhook related.
</Tip>

## Common scenarios

| Symptom | Likely cause | Where to check |
| - | - | - |
| AI never replies to any Freshchat chat | Webhook URL not added in Freshchat, or the **Message Create** event is unchecked | Freshchat **Admin Settings → Integrations & APIs → Webhooks** |
| AI replies to some chats but not others | Routing mode is **Assigned-only** and those chats aren't being assigned to the default agent email | OpenCX [FreshChat settings](https://platform.open.cx/settings/integrations) + Freshchat assignment rules |
| Assigned-only mode never picks up chats, even when assigned | **Conversation Assignment** event unchecked on the webhook — OpenCX never hears about the assignment | Freshchat **Admin Settings → Integrations & APIs → Webhooks** |
| Private handoff note missing inside Freshchat | The **Default Agent Email** no longer resolves to an agent in Freshchat (agent deleted, email changed) | Freshchat **Admin Settings → Team** |
| Saved handoff marker says "not found in Freshchat" | The selected marker property does not exist as an editable checkbox property in Freshchat, or your role can view but not create conversation properties | Freshchat **Admin Settings → Conversation properties**; ask a Freshchat admin to create `cf_opencx_handed_off` |
| Conversations resolved in Freshchat stay open in OpenCX | **Conversation Resolution** event unchecked on the webhook | Freshchat **Admin Settings → Integrations & APIs → Webhooks** |
| None of the above | Open a support request with the session ID, the Freshchat conversation ID, and a short description | [support@open.cx](mailto:support@open.cx) |

<Info>
  **Fastest path to root cause:** open the failing OpenCX session from your
  [Inbox](https://platform.open.cx/inbox). The session stores the Freshchat
  conversation URL — one click jumps you to the exact Freshchat thread to
  compare what OpenCX saw against what Freshchat shows.
</Info>

### **"Failed to verify credentials" on Test & Save**

<Tooltip>
  Likely cause
</Tooltip>

: wrong domain format, revoked token, or insufficient token permissions.

**Fix:** enter the plain domain (`yourcompany.freshchat.com`, no `https://`). Regenerate the token in [Freshchat Admin Settings → Integrations & APIs](https://support.freshchat.com/en/support/solutions/articles/50000000306-freshchat-apis) and confirm it has conversation management permissions.

### **Token was rotated in Freshchat and the integration went silent**

<Tooltip>
  Likely cause
</Tooltip>

: token rotated in Freshchat, not updated in OpenCX.

**Fix:** paste the new token into [Settings → Integrations → FreshChat](https://platform.open.cx/settings/integrations) and click **Test & Save**. Then revoke the old token in Freshchat.

### **Customer contacts merging unexpectedly**

<Tooltip>
  Likely cause
</Tooltip>

: same email shared across Freshchat users.

**Fix:** this is expected behavior — see [Conversation flow → Channel-specific details](/integrations/freshchat/conversations#channel-specific-details). Give each end user a distinct email in Freshchat if you need separate OpenCX contacts.

### **Integration went silent after disconnect and reconnect**

<Tooltip>
  Likely cause
</Tooltip>

: the webhook was removed or its events were unchecked in Freshchat while the
integration was disconnected.

**Fix:** open Freshchat **Admin Settings → Integrations & APIs → Webhooks** and confirm the webhook still exists, its endpoint matches the URL shown in [Settings → Integrations → FreshChat](https://platform.open.cx/settings/integrations), and all four events are checked.

### **AI replies arrive from the wrong agent name**

<Tooltip>
  Likely cause
</Tooltip>

: the Freshchat agent was renamed or the default agent email was pointed at a
different person.

**Fix:** rename the agent in Freshchat, or change **Default Agent Email** in [OpenCX settings](https://platform.open.cx/settings/integrations) to the intended agent. Create a dedicated agent (for example *OpenCX AI*) if you want a stable brand on replies.

### **Handoff marker property is missing**

<Tooltip>
  Likely cause
</Tooltip>

: `cf_opencx_handed_off` has not been created in Freshchat as an editable
checkbox property, or your Freshchat role cannot create conversation properties.

**Fix:** ask a Freshchat admin to create an editable checkbox conversation property named `cf_opencx_handed_off`, then select it in [Settings → Integrations → FreshChat](https://platform.open.cx/settings/integrations). If you cannot create a new field, select an existing editable custom checkbox property only if your routing rules can safely use it as the handoff marker.

## Limits & timing

| | Value |
| - | - |
| **Freshchat API call timeout** | 10 seconds per call |
| **Webhook deduplication window** | 24 hours |
| **Retry / backoff** | None — OpenCX does not retry transient Freshchat failures beyond the single call |
| **Freshchat API rate limit** | Governed by your Freshchat plan — typical limit is 60 requests per minute |

<Note>
  OpenCX does not throttle or queue calls against the Freshchat rate limit.
  Sustained high-volume chat may hit Freshchat's per-minute ceiling during peaks
  — if you expect spikes, contact support to discuss pacing.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Freshchat" icon="plug" href="/integrations/freshchat/connect">
    Re-verify credentials, webhook events, and routing mode.
  </Card>

  <Card title="Conversation flow" icon="diagram-project" href="/integrations/freshchat/conversations">
    Re-check how chats match to sessions and how handoff lands.
  </Card>

  <Card title="Overview" icon="comment" href="/integrations/freshchat/overview">
    What the Freshchat integration does and how it fits with your team.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Connect Freshdesk ticketing
Source: https://docs.open.cx/integrations/freshdesk/connect

Create a dedicated OpenCX admin agent in Freshdesk, verify its API key, choose intake and handoff routing, and add two automation rules.

The Freshdesk integration uses the <Tooltip>API key</Tooltip> of a dedicated OpenCX agent to read and write tickets, plus two Freshdesk automation rules that push ticket events back to OpenCX.

<FreshdeskFlow />

<Info>
  Setup takes about 15 minutes. You need admin access in both Freshdesk and your
  OpenCX organization, and a Freshdesk **Growth, Pro, or Enterprise** plan — the
  webhook automation action isn't available on the free plan.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="A dedicated OpenCX agent with admin privileges" icon="user-shield">
    Create a dedicated agent in Freshdesk (for example *OpenCX AI*) and give it **admin** privileges. The AI posts replies as this agent, so customers see its name on every AI message — don't reuse a person's account. Admin is a hard requirement: OpenCX needs it to tell agents and contacts apart at runtime, and **verification rejects non-admin API keys**.
  </Accordion>

  <Accordion title="Ticket scope: Global Access (all tickets)" icon="lock-open">
    Set the agent's **Scope** to **Global Access** (all tickets) under **Admin → Agents → \[the OpenCX agent] → Scope**. This is *separate* from the admin role and is **not** checked at connect time — a restricted-scope admin key verifies fine, then silently fails: OpenCX reads each ticket back from the API, and Freshdesk returns **403 "You are not authorized to perform this action"** for any ticket outside the agent's scope, so those tickets never appear in your inbox.

    * **Auto-handle-all intake** → Global Access is **required** (the AI must read every new ticket).
    * **Assigned-only intake** → Global Access is still strongly recommended. "Group Access" works only if the AI agent belongs to every group whose tickets it receives; "Restricted (assigned tickets only)" reads only tickets already assigned to the agent and 403s on anything routed by group or default-group rules.
  </Accordion>

  <Accordion title="Permission to create automation rules" icon="gears">
    Webhook delivery runs through two automation rules you create under **Admin →
    Workflows → Automations**. Only Freshdesk admins can create them.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="key">
    Required to save integration settings in [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Accordion>
</AccordionGroup>

## Required permissions

The API key inherits the OpenCX agent's role and scope. The agent must be able to do everything below — granting **admin** + **Global Access** scope covers all of it in one step.

| Capability | Why OpenCX needs it | Enforced at connect? |
| - | - | - |
| **Admin role** | Read agents (`/agents`) to tell agents from contacts and attribute replies/notes correctly | ✅ Yes — non-admin keys are rejected |
| **Global Access** ticket scope | Read every ticket the AI must handle (`GET /tickets/{id}`); a narrower scope 403s on out-of-scope tickets | ❌ No — verify silently passes, then tickets vanish at runtime |
| Reply to tickets & add notes | Post AI replies (autopilot) and private drafts (assist mode) | ❌ No |
| Edit ticket properties & assign tickets | Sync tags/status, set the handoff marker field, and route handoffs to an agent or group | ❌ No |
| Read contacts | Resolve the requester's name/email for the session | ❌ No |
| Create automation rules | Build the two **Trigger Webhook** rules that push events to OpenCX | ❌ No (Freshdesk-side) |

<Warning>
  Only the **admin** check runs at connect — **ticket scope is not verified**. A Global-Access admin is the safe default; anything narrower connects successfully and then silently drops tickets with a 403. If tickets stop appearing, check the agent's Scope first.
</Warning>

## Setup

<Steps>
  <Step title="Copy the OpenCX agent's API key">
    Log in to Freshdesk **as the dedicated OpenCX agent**, open **Profile settings**, and copy **Your API Key**.

    See [Freshdesk's API key guide](https://support.freshdesk.com/en/support/solutions/articles/215517) if the page has moved.

    <Warning>
      The key is bound to that agent. If the agent is deactivated or loses admin privileges, the integration stops working.
    </Warning>
  </Step>

  <Step title="Open Freshdesk in OpenCX">
    In your OpenCX dashboard, go to [**Settings →
    Integrations**](https://platform.open.cx/settings/integrations) and select
    **Freshdesk**.
  </Step>

  <Step title="Enter and verify your credentials">
    | Field | Value |
    | - | - |
    | **Domain** | Your Freshdesk domain — for example `yourcompany.freshdesk.com`. Include the full domain, do not prefix with `https://`. |
    | **API Key** | The OpenCX agent's API key you just copied. |

    Click **Verify**. OpenCX calls the Freshdesk API, confirms the key belongs to an **admin** agent, and shows the connected agent's name and email so you can confirm it's the right account. A wrong domain, bad key, or non-admin agent returns an error and nothing persists.
  </Step>

  <Step title="Pick an intake mode">
    The **Auto Handle All Incoming Tickets** toggle controls which new tickets the AI picks up.

    <AccordionGroup>
      <Accordion title="Auto-handle all incoming tickets (toggle on)" icon="bolt">
        The AI answers every new ticket regardless of assignment. Use this when the AI is the front door to your helpdesk.
      </Accordion>

      <Accordion title="Assigned-only (toggle off)" icon="filter">
        The AI only answers new tickets that Freshdesk has assigned to the OpenCX agent, or that land in the **Default Group** you select. Use this when your existing Freshdesk routing rules decide which tickets go to the AI.
      </Accordion>
    </AccordionGroup>

    The gate applies to **new** tickets only — once OpenCX is tracking a ticket, status and replies keep syncing even after handoff.
  </Step>

  <Step title="Choose the handoff routing">
    Choose what OpenCX should do in Freshdesk after the AI hands off to a human.

    | Routing | What happens | When to use it |
    | - | - | - |
    | **Unassign ticket** *(default)* | OpenCX removes the OpenCX agent from the ticket and reopens it. | Use this when your team works from the unassigned queue or manually triages handoffs. |
    | **Let Freshdesk automation route** | OpenCX unassigns the ticket and sets the handoff marker field — routing only happens if you have an automation rule keyed on the marker. | Use this when routing should stay inside Freshdesk rules and queues. |
    | **Assign to a specific agent** | OpenCX assigns the ticket to the **Handoff Agent ID** you enter and sets the marker. | Use this for a fixed fallback agent or small teams without routing automation. |
    | **Assign to a group** | OpenCX assigns the ticket to the **Handoff Group** you select and sets the marker. | Use this when a team queue should receive handoffs. |

    For the marker-based routings, OpenCX sets a custom checkbox ticket field on handoff. Create it in Freshdesk under **Admin → Workflows → Ticket fields**:

    | Field | Value |
    | - | - |
    | **Label** | `OpenCX handed off` |
    | **Internal/API name** | `cf_opencx_handed_off` |
    | **Type** | Checkbox |

    Then select it as the **Handoff Marker Field** in OpenCX. If you point your automation at the marker, make sure those rules never route marked tickets back to the OpenCX agent.

    <Note>
      If a configured handoff target becomes invalid later (agent deleted, group removed), OpenCX never leaves a handed-off ticket assigned to the AI — it falls back to unassigning and setting the marker so your rules can still catch it.
    </Note>
  </Step>

  <Step title="Optional: additional AI agents">
    By default the AI answers as the one connected agent. If different customers should see different names — one support persona per region or brand, say — create a Freshdesk agent for each persona, then tick them under **Additional AI agents**. The connected agent is always included.

    A ticket assigned to any ticked agent is handled by the AI and answered **as that agent**: its name on the reply, its own Freshdesk signature. Your Freshdesk assignment rules decide which persona a customer sees, so route each mailbox, group, or product to the matching agent. Reassigning a ticket from one AI agent to another switches the persona on the next reply; assigning it to a person still hands it off.

    <Note>
      Only agents in your Freshdesk account can be ticked. Give each persona agent its own name and signature in Freshdesk — OpenCX reads both from there.
    </Note>
  </Step>

  <Step title="Optional: assist-mode footer">
    If you run

    <Tooltip>
      assist mode
    </Tooltip>

    on any channel, the AI posts drafts as private notes. The **Assist Mode
    Footer** text is appended to each draft so reps can tell AI drafts from human
    notes at a glance.
  </Step>

  <Step title="Save and copy your webhook URL">
    Click **Save**. OpenCX validates the credentials again, stores the settings, and displays a **Webhook URL** unique to your organization, plus the two JSON payloads for the next step.

    On first connect, OpenCX also runs a one-time **backfill**: open and pending tickets from the last \~180 days are imported into your inbox as history. The backfill never triggers AI replies on old tickets.

    <Warning>
      The webhook URL contains a signed token tied to your organization. Anyone with it can post events into your OpenCX pipeline. Treat it like a password.
    </Warning>
  </Step>

  <Step title="Create the two automation rules in Freshdesk">
    In Freshdesk, open **Admin → Workflows → Automations** and create two rules. Both use the action **Trigger Webhook** with request type **POST**, encoding **JSON**, content **Advanced**, pointing at your OpenCX webhook URL.

    **Rule 1 — Ticket Creation tab.** Trigger on ticket creation and paste Payload 1 from the OpenCX dialog:

    ```json theme={"dark"}
    {
      "ticketId": "{{ticket.id}}",
      "triggered_event": "ticket_created",
      "assigneeId": "{{ticket.agent.id}}",
      "groupId": "{{ticket.group.id}}",
      "requesterEmail": "{{ticket.contact.email}}",
      "requesterName": "{{ticket.contact.name}}",
      "requesterPhone": "{{ticket.contact.phone}}"
    }
    ```

    **Rule 2 — Ticket Updates tab.** Set **Action performed by** to **Agent or requester** (the default, *Agent*, silently drops customer replies), trigger on **Agent is changed**, **Reply is sent**, **Note is added**, and **Ticket property changed (Status)**, add at least one condition (Freshdesk requires one; **Source is any of Email** works, but never a group or agent condition, since a new ticket is not assigned yet), and paste Payload 2:

    ```json theme={"dark"}
    {
      "ticketId": "{{ticket.id}}",
      "triggered_event": "{{Triggered event}}",
      "assigneeId": "{{ticket.agent.id}}",
      "groupId": "{{ticket.group.id}}",
      "requesterEmail": "{{ticket.contact.email}}",
      "requesterName": "{{ticket.contact.name}}",
      "requesterPhone": "{{ticket.contact.phone}}"
    }
    ```

    These optional fields are performance hints, not requirements:

    * `assigneeId` / `groupId` let OpenCX skip tickets that aren't for the AI agent without an extra API call.
    * `requesterEmail` / `requesterName` / `requesterPhone` let OpenCX identify the customer without a separate contact lookup.

    They're safe to include even if your Freshdesk plan doesn't expose a placeholder — unresolved or empty values are ignored, and OpenCX always re-reads the ticket from the API before acting.

    <Warning>
      Without Rule 1, the AI never sees new tickets. Without Rule 2, customer replies don't reach the AI and status changes in Freshdesk don't sync back to OpenCX.
    </Warning>

    <Warning>
      **Assigned-only intake with a shared queue?** If the AI agent receives tickets through Freshdesk's automatic assignment (round-robin / load-balanced queue) rather than being assigned at creation, the **Agent is changed** trigger on Rule 2 is what tells OpenCX the ticket is now the AI's. Without it, newly assigned tickets only surface when a later reply or status change happens. Note that Freshdesk may not fire automation rules for assignments performed by *automatic* assignment — if auto-assigned tickets still don't appear, assign the AI agent from a rule that also triggers the webhook, or have that rule fire on creation. Verify with a manual reassignment first: it should produce a ticket in your OpenCX inbox within seconds.
    </Warning>
  </Step>

  <Step title="Create a test ticket">
    Open a ticket as an end user (or use the Freshdesk portal). Within a few seconds:

    1. A new session appears in your [OpenCX Inbox](https://platform.open.cx/inbox) — email tickets land on the **Email** channel, portal/chat tickets on **Web**, phone tickets on **Phone**.
    2. The AI's answer appears on the Freshdesk ticket as the OpenCX agent — a public reply in autopilot, a private note in assist mode.

    If nothing appears, jump to [Troubleshooting](/integrations/freshdesk/troubleshooting).
  </Step>
</Steps>

## Importing your ticket history

Once ticketing is connected, the Freshdesk dialog offers **Import from Freshdesk**. It brings your existing Freshdesk tickets into OpenCX as sessions, each with the customer's first message and the full thread of replies and notes, attributed to the agents who wrote them. Closed tickets arrive closed, with their original dates.

Before anything starts, OpenCX checks the saved credentials against your account and shows what it found: how many tickets and contacts there are, whether the OpenCX agent can see every ticket, and whether your account archives old tickets. Fix anything that fails in Freshdesk, save the credentials again, and retry.

A few things to know:

* The import runs in the background and can take days for large accounts, because Freshdesk limits how quickly history can be read. You can close the dialog and check back.
* It never replies to anyone. Imported sessions are history, not new conversations, and nothing is sent to your customers or to Freshdesk.
* Running it again later only adds tickets that are new or changed since the previous run.
* If your Freshdesk plan archives tickets, closed tickets inactive for more than 120 days are not reachable and are not imported. The check tells you when this applies.
* File attachments are listed by name on each message but the files themselves are not copied.

## Rotating the API key

If you regenerate the OpenCX agent's API key in Freshdesk, paste the new key into [Settings → Integrations → Freshdesk](https://platform.open.cx/settings/integrations) and save. The saved key is never displayed back — the field is blank on edit and you re-enter it to change credentials. The webhook URL does not change when you rotate the key.

## Disconnecting

In OpenCX, open the Freshdesk integration and click **Disconnect**. Then in Freshdesk, delete the two automation rules. Tickets already imported stay in your OpenCX inbox; no new Freshdesk events flow in, and the AI stops posting on tickets.

***

## Related Documentation

<CardGroup>
  <Card title="Ticket flow" icon="diagram-project" href="/integrations/freshdesk/tickets">
    How tickets match to sessions, how handoff routes them, how resolutions
    sync.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/freshdesk/troubleshooting">
    Verification failing, webhook silent, handoff not routing.
  </Card>

  <Card title="Overview" icon="ticket" href="/integrations/freshdesk/overview">
    What the Freshdesk integration does and how it fits with your team.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Freshdesk ticketing overview
Source: https://docs.open.cx/integrations/freshdesk/overview

Run Freshdesk as the surface your agents work in while OpenCX answers tickets, escalates with context, and keeps ticket status in sync.

OpenCX works alongside your team inside Freshdesk. The AI replies on the same ticket your customer opened, escalates cleanly when automation stops, and writes an AI-drafted private note on every handoff and resolution so your rep picks up with full context — no separate inbox, no copy-paste.

<Tip>
  Setup starts at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="AI replies on your live Freshdesk tickets" icon="robot">
    When a customer opens or updates a ticket, OpenCX receives the event, matches it to an existing session or opens a new one, and the AI posts its answer in Freshdesk as the dedicated OpenCX agent. On email tickets the reply emails the requester; on portal and chat tickets it lands in the thread. <Tooltip href="/handoff/topics">Autopilot</Tooltip> controls which topics the AI answers versus escalates.
  </Accordion>

  <Accordion title="Assist mode drafts instead of sending" icon="pen-to-square">
    On channels where you enable assist mode, the AI posts its answer as a **private note** instead of a public reply. Your rep reviews the draft inside Freshdesk and sends it themselves. An optional footer marks assist notes so reps can tell them apart at a glance.
  </Accordion>

  <Accordion title="Handoff routes the ticket, not just the conversation" icon="user-group">
    When the AI escalates, OpenCX reopens the ticket, posts a private handoff note with the AI summary and detected sentiment, and routes it your way: unassign it, mark it for your Freshdesk automation rules, assign it to a specific agent, or assign it to a group. The customer never sees the note.
  </Accordion>

  <Accordion title="Two ways to route tickets to the AI" icon="route">
    Pick whichever fits your routing rules:

    * **Auto-handle all incoming tickets** — the AI picks up every new ticket. Use this when the AI is the front door.
    * **Assigned-only** — the AI only answers tickets your Freshdesk rules assign to the OpenCX agent or place in the default group you configure. Use this when your existing routing decides which tickets go to the AI.
  </Accordion>

  <Accordion title="Status stays in sync both ways" icon="rotate">
    When the AI auto-resolves, OpenCX sets the Freshdesk ticket to **Resolved** and posts a private resolution note with the summary and sentiment. When a rep resolves or closes the ticket in Freshdesk, OpenCX closes the matching session. Reopen the ticket and the session reopens too.
  </Accordion>
</AccordionGroup>

## Observability

Every Freshdesk ticket the AI touches is traceable from OpenCX back to the ticket — and back from Freshdesk through the private notes the AI wrote.

<AccordionGroup>
  <Accordion title="Full ticket thread in your OpenCX inbox" icon="link">
    OpenCX ingests the whole ticket conversation — customer messages, public agent replies, and private notes — into the matching session, so your [OpenCX Inbox](https://platform.open.cx/inbox) shows the same thread your reps see in Freshdesk, including attachments.
  </Accordion>

  <Accordion title="AI summary visible inside Freshdesk" icon="note-sticky">
    Every handoff and every AI resolution drops a private note onto the ticket. The note contains the AI summary and detected sentiment. Your reps read it in Freshdesk before they type a word.
  </Accordion>

  <Accordion title="Tags mirror what happened" icon="tags">
    OpenCX tags every ticket it touches with `opencx` plus `opencx_autopilot` or `opencx_assist_mode`, and mirrors the ticket's Freshdesk tags and group name onto the OpenCX session — so you can filter both sides by what the AI did.
  </Accordion>

  <Accordion title="Reassign to resume AI handling" icon="arrows-rotate">
    Assignment is the source of truth. Reassign a handed-off ticket back to the OpenCX agent in Freshdesk and the AI resumes answering; assign it to a human and the AI goes quiet — no OpenCX-side toggle needed.
  </Accordion>
</AccordionGroup>

<Note>
  Looking to import Freshdesk **Solution articles** into the AI's knowledge instead? That's the separate [Freshdesk knowledge source](/knowledge/sources/freshdesk/overview).
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Freshdesk" icon="plug" href="/integrations/freshdesk/connect">
    Create the OpenCX agent, paste your API key, set up the two automation rules.
  </Card>

  <Card title="Ticket flow" icon="diagram-project" href="/integrations/freshdesk/tickets">
    How tickets reach the AI, how handoff routes them, how resolutions sync.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/freshdesk/troubleshooting">
    AI not replying, handoff not routing, tickets not closing.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Freshdesk ticket flow
Source: https://docs.open.cx/integrations/freshdesk/tickets

How Freshdesk tickets reach the AI, how autopilot and assist mode reply, how handoff routes the ticket, and how resolutions sync both ways.

After setup, every Freshdesk ticket that passes your intake gate flows through OpenCX. The AI replies on the ticket as the OpenCX agent, hands off when it can't resolve, and resolves tickets when it can.

## How a ticket lands on the AI

```mermaid theme={"dark"}
flowchart LR
  A[Customer opens or updates a ticket] --> B[Freshdesk automation rule fires webhook]
  B --> C[OpenCX matches the ticket to a session]
  C --> D[AI replies as the OpenCX agent]
```

The match step is the load-bearing one. OpenCX uses the Freshdesk ticket ID to decide whether to append to an existing session or open a new one, and ingests the **whole ticket thread** — customer messages, public agent replies, and private notes — so the [OpenCX Inbox](https://platform.open.cx/inbox) mirrors what your reps see in Freshdesk.

The ticket's source picks the OpenCX channel: email tickets become **Email** sessions, portal/chat/feedback-widget tickets become **Web** sessions, and phone tickets become **Phone** sessions. Channel settings — including autopilot vs assist mode — apply per channel.

## Intake gate

The **Auto Handle All Incoming Tickets** toggle on the [Freshdesk integration settings](https://platform.open.cx/settings/integrations) picks which **new** tickets the AI answers. See [Connect Freshdesk](/integrations/freshdesk/connect) for setup.

* **Auto-handle all incoming tickets** — the AI answers every new ticket.
* **Assigned-only** — the AI only answers new tickets assigned to the OpenCX agent (or any [additional AI agent](/integrations/freshdesk/connect#setup) you ticked) or placed in your configured default group.

Once a ticket is tracked, the gate no longer applies: replies, notes, and status changes keep syncing even after the ticket moves to a human.

## Which agent replies

The AI answers a ticket **as the agent it is assigned to**, provided that agent is the connected OpenCX agent or one of the additional AI agents in your settings. The reply carries that agent's name and Freshdesk signature. Tickets assigned to nobody, or in the default group, are answered as the connected agent. This is how one OpenCX organization presents a different support persona per region, brand, or mailbox: create an agent per persona in Freshdesk, tick them in OpenCX, and let your Freshdesk assignment rules pick.

## How the AI replies

<AccordionGroup>
  <Accordion title="Autopilot — public reply" icon="paper-plane">
    On channels with autopilot, the AI posts a **public reply** as the OpenCX agent. On email tickets this emails the requester; on portal tickets it appears in the thread.
  </Accordion>

  <Accordion title="Assist mode — private draft" icon="pen-to-square">
    On channels with assist mode, the AI posts its answer as a **private note** the customer never sees. Your rep reviews and sends it. The optional assist-mode footer is appended so drafts are recognizable.
  </Accordion>
</AccordionGroup>

Public replies and private drafts preserve paragraphs, line breaks, bold and italic text, lists, and links. Existing formatting in replies sent from the OpenCX Inbox is preserved too.

Either way, OpenCX tags the ticket with `opencx` plus `opencx_autopilot` or `opencx_assist_mode`, so you can build Freshdesk views and reports on AI-touched tickets.

## Add CC recipients from an AI workflow

A synchronous **AI Trigger** workflow can add verified recipients to the public
AI reply that follows it. In **Aggregate Workflow Results**, set **Freshdesk
reply CC** (`freshdeskReplyCc`) to an array of email addresses from your verified
customer or order lookup. Keep the explanation for the AI in the separate
**Result** field.

```json theme={"dark"}
{
  "result": {
    "status": "ready_to_loop_in",
    "copiedIn": "seller"
  },
  "freshdeskReplyCc": ["seller@example.com"]
}
```

The workflow prepares the recipients; it does not send an email. OpenCX merges
them with existing Freshdesk CCs when sending the same public AI reply. Duplicate
addresses are removed. Addresses supplied through the CC field are kept separate
from the workflow result shown to the AI. Do not add a separate reply action or try to update
`cc_emails` through the Freshdesk ticket-update endpoint.

* Use a synchronous workflow called by the AI on a Freshdesk-linked session.
  Background workflows and assist-mode private drafts cannot loop recipients in.
* Verify that the requester is authorized to contact the other party before
  returning their address. Configure the AI's reply wording without exposing
  lookup data in the message body.
* A successful workflow result means the recipients are prepared, not that an
  email has already been delivered. A skipped, cancelled, or handed-off AI reply
  does not send these additional recipients a message.
* Each workflow can prepare up to 50 additional recipients for that AI turn.
  Recipients from multiple workflows are combined. Existing
  Freshdesk CCs are preserved. Freshdesk may retain recipients for later replies; this option
  does not remove them from Freshdesk afterwards. A newer customer message does
  not inherit additional recipients prepared for an earlier message.
* If the workflow completes in a context that cannot send these CCs, its result
  includes a delivery warning. Invalid recipient values also produce a warning
  after the workflow completes; they do not retry earlier workflow steps.
* If Freshdesk is temporarily unavailable when OpenCX reads the existing CCs,
  the reply is saved for deferred delivery. Read failures are retried; a reply
  whose send was already attempted requires inspection before it can be resent.
  Deferred replies recheck human takeover immediately before sending.

## When the AI hands off

<Steps>
  <Step title="The AI decides it cannot resolve">
    Handoff triggers follow your global handoff rules — topics not in the Autopilot allowlist, explicit customer asks for a human, confidence thresholds, office-hours rules.
  </Step>

  <Step title="A private handoff note lands on the ticket">
    OpenCX posts a private note containing the AI summary and detected sentiment.
    The note is Freshdesk-internal — your customer never sees it. Your rep reads
    the summary before typing.
  </Step>

  <Step title="OpenCX reopens and routes the ticket">
    The ticket moves back to **Open**, then your configured routing applies:
    unassign it, unassign + set the handoff marker for your Freshdesk automation,
    assign it to your handoff agent, or assign it to your handoff group. If a
    configured target is invalid, OpenCX falls back to unassign + marker — a
    handed-off ticket is never left assigned to the AI.
  </Step>

  <Step title="Your rep picks up the ticket">
    Your rep replies in Freshdesk as normal. Their public replies and private notes sync into the OpenCX session timeline, but the AI stays silent — assignment to a human marks the session as handed off.
  </Step>
</Steps>

<Info>
  **Assignment is the switch.** Reassign the ticket back to the OpenCX agent (or
  any additional AI agent) in Freshdesk and the AI resumes answering on the next
  customer message. Assign it to a human and the AI goes quiet. No OpenCX-side
  toggle needed.
</Info>

## When the AI resolves

<Steps>
  <Step title="The AI session auto-resolves">
    OpenCX's auto-resolution logic closes the session when the conversation is complete — for example, after a successful answer with no further customer response.
  </Step>

  <Step title="OpenCX resolves the Freshdesk ticket">
    OpenCX posts a private resolution note with the summary and sentiment, then sets the ticket status to **Resolved**. If the ticket is no longer assigned to the AI agent — a human took it, or it was unassigned — OpenCX leaves its status alone.
  </Step>
</Steps>

## When a rep changes status in Freshdesk

Status syncs on every webhook delivery:

* Rep sets the ticket to **Resolved** or **Closed** → the OpenCX session closes as resolved.
* Ticket is **reopened** (by a rep or a customer reply) → the closed OpenCX session reopens.
* Ticket is marked **spam** or deleted → the linked session closes.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Attachments are re-hosted, both directions" icon="paperclip">
    Customer and agent attachments on the ticket are copied into OpenCX storage (Freshdesk's links expire) and land on the session, so the AI sees them alongside text. AI replies can carry attachments back onto the ticket. Freshdesk caps attachments at 20 MB total per reply or note.
  </Accordion>

  <Accordion title="Contact identity comes from the requester" icon="fingerprint">
    OpenCX resolves the ticket requester to a contact using the email and phone on
    the Freshdesk contact record. If requester details are missing, the session is
    still created — just without contact details.
  </Accordion>

  <Accordion title="Freshdesk tags and group mirror onto the session" icon="tags">
    The ticket's Freshdesk tags and assigned group name become OpenCX session tags
    on every sync, so inbox filters and reports can segment by Freshdesk
    attributes.
  </Accordion>

  <Accordion title="Own replies are not re-ingested" icon="rotate-right">
    Freshdesk fires the update webhook for the AI's own replies too. OpenCX
    recognizes the OpenCX agent's messages and skips them, so the AI never answers
    itself and nothing is duplicated. Re-delivered webhooks are deduplicated by
    message ID.
  </Accordion>

  <Accordion title="Historical tickets from before the integration" icon="clock-rotate-left">
    On first connect, OpenCX backfills open and pending tickets from the last \~180 days as read-only history. The AI never replies to backfilled tickets — it only engages from the next customer message after connection.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Troubleshooting" icon="wrench" href="/integrations/freshdesk/troubleshooting">
    AI not replying, handoff not routing, tickets not closing.
  </Card>

  <Card title="Connect Freshdesk" icon="plug" href="/integrations/freshdesk/connect">
    Re-verify credentials, automation rules, and routing settings.
  </Card>

  <Card title="Overview" icon="ticket" href="/integrations/freshdesk/overview">
    What the Freshdesk integration does and how it fits with your team.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Freshdesk ticketing troubleshooting
Source: https://docs.open.cx/integrations/freshdesk/troubleshooting

Debug Freshdesk credentials, automation rules, intake gating, handoff routing, marker fields, and resolution sync.

Before debugging, have this ready:

* Your Freshdesk <Tooltip>domain</Tooltip> and the email of the dedicated OpenCX agent whose <Tooltip>API key</Tooltip> you saved.
* A specific OpenCX session ID (from [Inbox](https://platform.open.cx/inbox)) or Freshdesk ticket ID where the problem shows.
* Your intake mode (**Auto Handle All Incoming Tickets** on/off) and configured **Default Group**, if any.

<Tip>
  Re-run **Verify** in [Settings →
  Integrations](https://platform.open.cx/settings/integrations) → Freshdesk as
  your first step. Most issues are credential or automation-rule related.
</Tip>

## Common scenarios

| Symptom | Likely cause | Where to check |
| - | - | - |
| AI never replies to any ticket | Automation rules missing, or Rule 1 (Ticket Creation) doesn't fire the webhook | Freshdesk **Admin → Workflows → Automations** — check both rules and their activity logs |
| AI replies to new tickets but not to customer follow-ups | Rule 2 (Ticket Updates) missing, or its events don't include **Reply is sent** | Freshdesk **Admin → Workflows → Automations** → Ticket Updates rule |
| AI replies to some tickets but not others | Intake mode is assigned-only and those tickets aren't assigned to the OpenCX agent (or a ticked additional AI agent) or in the default group | OpenCX [Freshdesk settings](https://platform.open.cx/settings/integrations) + Freshdesk assignment rules |
| Tickets assigned to a persona agent are ignored, or its replies show the connected agent's name | The persona agent isn't ticked under **Additional AI agents**, so OpenCX treats it as a human | OpenCX [Freshdesk settings](https://platform.open.cx/settings/integrations) → tick the agent and save |
| Tickets silently never appear and don't error in OpenCX (Freshdesk returns 403 "not authorized") | The OpenCX agent's **ticket scope** is too narrow (Group or Restricted), so OpenCX can't read those tickets back from the API | Freshdesk **Admin → Agents → \[OpenCX agent] → Scope** — set to **Global Access**. Not checked at connect, so a restricted admin key looks connected but drops tickets |
| Tickets assigned to the AI agent (via a queue) never appear; only ones that later get a reply or update do | Rule 2 (Ticket Updates) doesn't include **Agent is changed**, so the assignment itself never reaches OpenCX — or Freshdesk isn't firing automations for *automatic* (round-robin) assignment | Freshdesk **Admin → Workflows → Automations** → add **Agent is changed** to the Ticket Updates rule. If auto-assigned tickets still don't appear, assign the AI agent from a rule that also triggers the webhook |
| Handed-off tickets aren't routed by your automation | Marker field doesn't exist in Freshdesk, or your rules don't match it | Freshdesk **Admin → Workflows → Ticket fields** — create `cf_opencx_handed_off` as a checkbox |
| Tickets resolved in Freshdesk stay open in OpenCX | Rule 2 doesn't include **Ticket property changed (Status)** | Freshdesk **Admin → Workflows → Automations** → Ticket Updates rule |
| None of the above | Open a support request with the session ID, the Freshdesk ticket ID, and a short description | [support@open.cx](mailto:support@open.cx) |

### **Verification fails with "admin privileges" or a 403**

<Tooltip>
  Likely cause
</Tooltip>

: the API key belongs to a non-admin agent.

**Fix:** in Freshdesk, give the dedicated OpenCX agent the **admin** role (or copy the key from an admin agent's profile), then re-run **Verify**. The dialog shows the connected agent's name and email — confirm it's the dedicated OpenCX agent, not a person.

### **Verification fails with "failed to verify credentials"**

<Tooltip>
  Likely cause
</Tooltip>

: wrong domain format or stale API key.

**Fix:** enter the plain domain (`yourcompany.freshdesk.com`, no `https://`) and re-copy the key from the OpenCX agent's **Profile settings → Your API Key**. Saved settings never display the key back — re-enter it whenever you change credentials.

### **Webhook rule exists but nothing reaches OpenCX**

<Tooltip>
  Likely cause
</Tooltip>

: payload edited by hand, or webhook URL stale after a disconnect/reconnect.

**Fix:** copy the current webhook URL and both payloads from [Settings → Integrations → Freshdesk](https://platform.open.cx/settings/integrations) and paste them verbatim into the automation rules. Check the rule's activity log in Freshdesk to confirm it fires. Also note: the webhook action requires a **Growth, Pro, or Enterprise** Freshdesk plan.

### **AI answered a ticket your team should own**

<Tooltip>
  Likely cause
</Tooltip>

: intake mode is auto-handle-all.

**Fix:** turn **Auto Handle All Incoming Tickets** off and route AI tickets explicitly — assign them to the OpenCX agent or move them into the configured **Default Group** with your Freshdesk rules. The gate only applies to new tickets; tickets the AI already picked up keep syncing.

### **Handoff left the ticket unassigned instead of going to your agent/group**

<Tooltip>
  Likely cause
</Tooltip>

: the configured handoff agent or group was deleted or is invalid.

**Fix:** reopen [Settings → Integrations → Freshdesk](https://platform.open.cx/settings/integrations) and re-select a valid **Handoff Agent ID** or **Handoff Group**. The fallback is by design — treat unexpected unassigned+marked tickets as a signal the target needs fixing.

### **Marker field warning on save**

<Tooltip>
  Likely cause
</Tooltip>

: `cf_opencx_handed_off` (or your selected field) hasn't been created in
Freshdesk.

**Fix:** create a **checkbox** ticket field under **Admin → Workflows → Ticket fields** with the API name matching your selection, then save again. Until it exists, handoff still routes — the marker is simply skipped, so automation rules keyed on it won't fire.

### **Customer replies appear in OpenCX but the AI stopped answering**

<Tooltip>
  Likely cause
</Tooltip>

: the ticket is assigned to a human agent.

**Fix:** this is expected after handoff. To put the AI back on the ticket, reassign it to the OpenCX agent in Freshdesk — the AI resumes on the next customer message.

## Limits & timing

| | Value |
| - | - |
| **Webhook delivery retries** | Handled by Freshdesk — failed deliveries are retried automatically per Freshdesk's webhook policy |
| **Rate limiting** | OpenCX respects Freshdesk 429 responses and retries up to 3 times with backoff; trial Freshdesk accounts have low per-minute quotas |
| **Attachment size** | 20 MB total per reply or note (Freshdesk limit) |
| **Backfill window** | \~180 days of open/pending tickets, imported once on first connect |

***

## Related Documentation

<CardGroup>
  <Card title="Connect Freshdesk" icon="plug" href="/integrations/freshdesk/connect">
    Re-verify credentials, automation rules, and routing settings.
  </Card>

  <Card title="Ticket flow" icon="diagram-project" href="/integrations/freshdesk/tickets">
    Re-check how tickets match to sessions and how handoff lands.
  </Card>

  <Card title="Overview" icon="ticket" href="/integrations/freshdesk/overview">
    What the Freshdesk integration does and how it fits with your team.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Email in Front
Source: https://docs.open.cx/integrations/front/channels/email

Route email conversations from Front through OpenCX AI with handoff to your Front inbox.

Email is the most common channel for the Front integration. When a customer emails your support address and the conversation is assigned to the AI <Tooltip>teammate</Tooltip> (or is unassigned with that option enabled), OpenCX picks it up via webhook, generates a reply, and sends it back through Front as the AI teammate.

## Pre-requisites

<Warning>
  **Connect your Front workspace first.** The AI has nothing to respond to until the webhook is active — start with [Connect Front](/integrations/front/connect) and come back here.
</Warning>

* **Front connected and webhook active** — see [Connect Front](/integrations/front/connect).
* **Email channel configured in Front** — your Front inbox must be receiving emails (connected email account or forwarding address).

## How conversations land in Front

```mermaid theme={"dark"}
flowchart LR
  A[Customer emails support] --> B[Email arrives in Front]
  B --> C[AI replies via Front]
  C --> D{AI can resolve?}
  D -- Yes --> E[Resolution note + archive]
  D -- No --> F[Handoff note + unassign]
  F --> G[Rep picks up in Front]
  G --> H[Rep replies — customer inbox]
```

## Setting up

<Steps>
  <Step title="Confirm email is routing to Front">
    Send a test email to the address your Front inbox is configured to receive. The conversation should appear in your Front inbox.
  </Step>

  <Step title="Confirm the AI processes the email">
    If the conversation is assigned to the AI teammate (or unassigned with that option enabled), the AI should reply within a few seconds. Check that the reply appears as a message from the AI teammate.
  </Step>

  <Step title="Trigger a test handoff">
    Reply to the email thread with *"I want to talk to a human."* The AI should hand off — you'll see an internal handoff comment with summary and sentiment, and the conversation unassigned.
  </Step>

  <Step title="Verify the rep reply loop">
    Pick up the handed-off conversation in your Front inbox. Reply as a teammate — the message should land in the customer's email inbox.
  </Step>
</Steps>

<Tip>
  If the AI doesn't reply to emails, confirm the conversation is assigned to the AI teammate or that **Handle unassigned conversations** is enabled in [settings](/integrations/front/connect#settings-reference).
</Tip>

## What the rep sees

* The conversation appears in their **Front inbox** as an email thread.
* The full AI-to-customer transcript is already in the thread — no separate tool to check.
* An **internal handoff comment** with conversation summary and detected sentiment.
* Replies sent from the Front inbox land in the customer's email inbox.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Contact matching by email address" icon="address-book">
    OpenCX extracts the sender's email from the webhook payload and matches it to an existing contact. If no match is found, a new contact is created with the sender's name and email address. This means returning customers are automatically linked to their previous sessions.
  </Accordion>

  <Accordion title="Attachment handling" icon="paperclip">
    Email attachments are downloaded from Front's API using the authenticated connection and uploaded to OpenCX storage. The AI can reference supported file types (images, documents) in its reasoning. Each attachment retains its original filename and content type.
  </Accordion>

  <Accordion title="Teammate replies are skipped" icon="user">
    When a human rep replies to an email conversation in Front, the webhook sends an `outbound` event. OpenCX detects the teammate reply and skips it to avoid duplicate processing. The AI stays out of the way once a rep takes over.
  </Accordion>

  <Accordion title="Subject line preserved" icon="heading">
    Front preserves the email subject line on the conversation. The AI processes the message body content — it does not modify or set the subject.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Chat channel" icon="comments" href="/integrations/front/channels/web">
    Web chat conversation specifics.
  </Card>

  <Card title="Connect Front" icon="plug" href="/integrations/front/connect">
    API token, webhook, and teammate selection.
  </Card>

  <Card title="Front overview" icon="inbox" href="/integrations/front/overview">
    What else the Front integration covers.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/front/troubleshooting">
    AI not replying to emails, webhook errors, handoff not firing.
  </Card>
</CardGroup>


# Phone in Front
Source: https://docs.open.cx/integrations/front/channels/phone

Route phone call records from Front through OpenCX AI with handoff context for your reps.

When Front receives call records from a connected voice channel, OpenCX processes the conversation text — the transcribed or summarized content Front creates from the call. The AI responds to this content the same way it handles any other channel: it reads the message, generates a reply, and hands off when it can't resolve.

<Note>
  OpenCX processes the **text content** of call records in Front, not live audio. The voice interaction itself is handled by your phone provider and Front's voice integration. OpenCX steps in after the call content is available as a conversation in Front.
</Note>

## Pre-requisites

<Warning>
  **Connect your Front workspace first.** The AI has nothing to respond to until the webhook is active — start with [Connect Front](/integrations/front/connect) and come back here.
</Warning>

* **Front connected and webhook active** — see [Connect Front](/integrations/front/connect).
* **Voice/phone channel configured in Front** — your Front workspace must have a phone channel that creates conversation records from calls.

## How conversations land in Front

```mermaid theme={"dark"}
flowchart LR
  A[Call record created] --> B[Conversation in Front]
  B --> C[AI processes text content]
  C --> D{AI can resolve?}
  D -- Yes --> E[Resolution note + archive]
  D -- No --> F[Handoff note + unassign]
  F --> G[Rep picks up in Front]
```

## Setting up

<Steps>
  <Step title="Confirm call records route to Front">
    Make a test call to the phone number your Front workspace is connected to. A conversation should appear in your Front inbox with the call content.
  </Step>

  <Step title="Confirm the AI processes the conversation">
    If the conversation is assigned to the AI teammate (or is unassigned with that option enabled), the AI should generate a response based on the call content.
  </Step>

  <Step title="Trigger a test handoff">
    Create a call conversation where the content requests human help. The AI should hand off — you'll see an internal handoff comment and the conversation unassigned.
  </Step>

  <Step title="Verify the rep picks up">
    Pick up the handed-off conversation in your Front inbox. The full context should be visible in the thread for review.
  </Step>
</Steps>

## What the rep sees

* The conversation appears in their **Front inbox** with the call content.
* An **internal handoff comment** with summary and sentiment.
* The OpenCX session in [Inbox](https://platform.open.cx/inbox) shows the full AI reasoning and any tool calls made during processing.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Call content, not live audio" icon="file-lines">
    OpenCX processes the text body of the Front conversation created from the call. This is typically a transcription, voicemail summary, or call notes — whatever your phone provider and Front's voice integration produce. The AI does not interact with live audio through Front.
  </Accordion>

  <Accordion title="Channel mapping" icon="route">
    Front labels call messages with the `call` type. OpenCX maps this to the voice channel type internally, so sessions created from call records show as phone conversations in your OpenCX reporting.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Email channel" icon="envelope" href="/integrations/front/channels/email">
    Email conversation specifics.
  </Card>

  <Card title="Connect Front" icon="plug" href="/integrations/front/connect">
    API token, webhook, and teammate selection.
  </Card>

  <Card title="Front overview" icon="inbox" href="/integrations/front/overview">
    What else the Front integration covers.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/front/troubleshooting">
    AI not replying, webhook errors, handoff not firing.
  </Card>
</CardGroup>


# SMS in Front
Source: https://docs.open.cx/integrations/front/channels/sms

Route inbound SMS conversations from Front through OpenCX AI with handoff to your Front inbox.

SMS conversations that arrive in Front through a connected phone number are processed by OpenCX. The AI picks up the message via webhook, generates a reply, and posts it as the AI <Tooltip>teammate</Tooltip> — the response is sent back to the customer as an SMS through Front.

## Pre-requisites

<Warning>
  **Connect your Front workspace first.** The AI has nothing to respond to until the webhook is active — start with [Connect Front](/integrations/front/connect) and come back here.
</Warning>

* **Front connected and webhook active** — see [Connect Front](/integrations/front/connect).
* **SMS channel configured in Front** — your Front workspace must have a phone number receiving SMS messages.

## How conversations land in Front

```mermaid theme={"dark"}
flowchart LR
  A[Customer sends SMS] --> B[SMS arrives in Front]
  B --> C[AI replies via SMS]
  C --> D{AI can resolve?}
  D -- Yes --> E[Resolution note + archive]
  D -- No --> F[Handoff note + unassign]
  F --> G[Rep picks up in Front]
  G --> H[Rep replies — customer SMS]
```

## Setting up

<Steps>
  <Step title="Confirm SMS messages route to Front">
    Send a test SMS to the phone number your Front inbox is configured to receive. The conversation should appear in your Front inbox.
  </Step>

  <Step title="Confirm the AI processes the message">
    The AI should reply within a few seconds. Check that the reply appears as a message from the AI teammate and is delivered back as an SMS.
  </Step>

  <Step title="Trigger a test handoff">
    Send *"I want to talk to a human"* via SMS. The AI should hand off — you'll see an internal handoff comment and the conversation unassigned.
  </Step>

  <Step title="Verify the rep reply loop">
    Pick up the handed-off conversation in your Front inbox. Reply as a teammate — the message should land on the customer's phone as an SMS.
  </Step>
</Steps>

## What the rep sees

* The conversation appears in their **Front inbox** as an SMS thread.
* The full AI-to-customer transcript is already in the thread.
* An **internal handoff comment** with summary and sentiment.
* Replies sent from the Front inbox are delivered to the customer as SMS.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Contact matching by sender handle" icon="address-book">
    OpenCX extracts the sender's phone number from the webhook payload. The handle is matched against existing contacts. If no match is found, a new contact is created with the phone number as their identifier.
  </Accordion>

  <Accordion title="Message length" icon="ruler">
    SMS messages are limited by carrier standards (160 characters per segment for GSM-7 encoding). Long AI responses may be split across multiple SMS segments by Front's SMS provider. OpenCX sends the full response text — segmentation is handled downstream.
  </Accordion>

  <Accordion title="No multimedia (MMS) processing" icon="image">
    If a customer sends images or media via MMS, Front receives the attachments. OpenCX downloads and stores them, but the AI's ability to reference MMS content depends on the attachment type and Front's handling of MMS on the connected channel.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Email channel" icon="envelope" href="/integrations/front/channels/email">
    Email conversation specifics.
  </Card>

  <Card title="Connect Front" icon="plug" href="/integrations/front/connect">
    API token, webhook, and teammate selection.
  </Card>

  <Card title="Front overview" icon="inbox" href="/integrations/front/overview">
    What else the Front integration covers.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/front/troubleshooting">
    AI not replying to SMS, webhook errors, handoff not firing.
  </Card>
</CardGroup>


# Chat in Front
Source: https://docs.open.cx/integrations/front/channels/web

Route web chat and messaging conversations from Front through OpenCX AI with handoff to your Front inbox.

Web chat and messaging conversations that land in Front — including those from Front Chat, <Tooltip>Smooch</Tooltip>-connected platforms, and custom channels — are processed by OpenCX. The AI picks up the conversation via webhook, generates a reply, and posts it as the AI teammate.

## Pre-requisites

<Warning>
  **Connect your Front workspace first.** The AI has nothing to respond to until the webhook is active — start with [Connect Front](/integrations/front/connect) and come back here.
</Warning>

* **Front connected and webhook active** — see [Connect Front](/integrations/front/connect).
* **Chat or messaging channel configured in Front** — your Front workspace must be receiving chat messages through Front Chat, Smooch, or a custom integration.

## How conversations land in Front

```mermaid theme={"dark"}
flowchart LR
  A[Customer opens chat] --> B[Message arrives in Front]
  B --> C[AI replies in chat]
  C --> D{AI can resolve?}
  D -- Yes --> E[Resolution note + archive]
  D -- No --> F[Handoff note + unassign]
  F --> G[Rep picks up in Front]
  G --> H[Rep replies — customer chat]
```

## Setting up

<Steps>
  <Step title="Confirm chat messages route to Front">
    Open your website or app where Front Chat (or a connected messaging platform) is installed and send a test message. The conversation should appear in your Front inbox.
  </Step>

  <Step title="Confirm the AI processes the message">
    The AI should reply within a few seconds. Check that the reply appears as a message from the AI teammate.
  </Step>

  <Step title="Trigger a test handoff">
    Send a message like *"I want to talk to a human"* in the chat. The AI should hand off — you'll see an internal handoff comment and the conversation unassigned.
  </Step>

  <Step title="Verify the rep reply loop">
    Pick up the handed-off conversation in your Front inbox. Reply as a teammate — the message should land in the customer's chat window.
  </Step>
</Steps>

<Tip>
  If the AI doesn't reply, check that the conversation is assigned to the AI teammate or that **Handle unassigned conversations** is enabled in [settings](/integrations/front/connect#settings-reference).
</Tip>

## What the rep sees

* The conversation appears in their **Front inbox** like any other chat thread.
* The full AI-to-customer transcript is already in the thread — no separate tool to check.
* An **internal handoff comment** with summary and sentiment.
* Replies typed in the Front inbox land back in the customer's chat window.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Messaging platform mapping" icon="grid-2">
    Front receives messages from various sources and labels them by type. OpenCX maps these to internal channel types:

    | Front message type | OpenCX channel |
    | - | - |
    | `custom` (Front Chat) | Web |
    | `smooch` (third-party messaging) | Web |
    | `intercom` | Web |
    | Unknown types | Web (default) |

    The AI responds the same way regardless of the underlying messaging platform.
  </Accordion>

  <Accordion title="Real-time responses" icon="bolt">
    Chat conversations are processed immediately on webhook delivery. The AI typically replies within a few seconds of receiving a customer message.
  </Accordion>

  <Accordion title="Inline images and attachments" icon="image">
    Images customers send in chat are downloaded from Front's API and uploaded to OpenCX storage. The AI can reference them in its reasoning. Other attachment types retain their original filename and content type.
  </Accordion>

  <Accordion title="Custom channel identifiers" icon="code">
    If your Front workspace uses custom channels, the customer's handle (the identifier used to reach them) is extracted from the webhook payload. This is typically a username, user ID, or external reference depending on how your custom channel is configured.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Email channel" icon="envelope" href="/integrations/front/channels/email">
    Email conversation specifics.
  </Card>

  <Card title="Connect Front" icon="plug" href="/integrations/front/connect">
    API token, webhook, and teammate selection.
  </Card>

  <Card title="Front overview" icon="inbox" href="/integrations/front/overview">
    What else the Front integration covers.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/front/troubleshooting">
    AI not replying, webhook errors, handoff not firing.
  </Card>
</CardGroup>


# Connect Front
Source: https://docs.open.cx/integrations/front/connect

Generate an API token, enter credentials, select the AI teammate, and configure the webhook.

One-time setup: enter your Front API token, pick the <Tooltip>teammate</Tooltip> the AI replies as, paste a webhook URL into Front, and choose whether the AI handles unassigned conversations.

<FrontFlow />

<Info>
  This page covers the shared Front connection. Once connected, see the [channel pages](/integrations/front/channels/email) for per-channel verification steps.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Front workspace with API access" icon="key">
    You need a Front workspace on a plan that includes API access. You also need permissions to generate API tokens in **Settings → Developers → API tokens**.
  </Accordion>

  <Accordion title="Admin access in OpenCX" icon="shield-check">
    Only organization admins can connect integrations. Confirm your role at [**Settings → Organization**](https://platform.open.cx/settings).
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Generate an API token in Front">
    In Front, go to [**Settings → Developers → API tokens**](https://app.frontapp.com/settings/developers/tokens). Create a new token with the following scopes:

    * **Shared Resources** — read and write
    * **Private Resources** — read and write
    * **Provisioning** — read

    <Warning>
      Store the token securely — Front only shows it once. If you lose it, revoke and regenerate.
    </Warning>
  </Step>

  <Step title="Enter the API token in OpenCX">
    Open [**Settings → Ticketing System**](https://platform.open.cx/settings/ticketing) in your OpenCX dashboard. Select **Front** and enter your API token.

    Click **Connect**. OpenCX validates the token by calling the Front API. If validation fails, double-check the token has not been revoked and your Front plan includes API access.
  </Step>

  <Step title="Select the AI teammate">
    After credentials are saved, OpenCX loads your Front teammates. Pick the teammate account that represents the AI — this is who customers see replies from.

    <Warning>
      Every AI-generated reply is posted as this teammate. Choose a dedicated bot account (e.g. "AI Agent") rather than a real team member to avoid confusion.
    </Warning>
  </Step>

  <Step title="Copy the webhook URL">
    OpenCX displays a webhook URL after connection. Copy it and configure it in your Front app's [webhook settings](https://dev.frontapp.com/docs/webhooks-1).

    The webhook needs to receive these event types:

    | Event | Why OpenCX needs it |
    | - | - |
    | **Inbound message** | Process new customer messages and generate AI replies. |
    | **Outbound message** | Detect teammate replies so the AI doesn't re-process them. |
    | **Conversation archived** | Sync resolved status back to the OpenCX session. |

    <Warning>
      Without the webhook, OpenCX cannot receive conversation events. The AI will not respond to any messages until the webhook is active.
    </Warning>
  </Step>

  <Step title="Configure unassigned handling (optional)">
    Enable **Handle unassigned conversations** if you want the AI to respond to conversations that arrive without an assignee. When disabled, the AI only responds to conversations assigned to the selected teammate.
  </Step>

  <Step title="Send a test message">
    Send a test message through one of your Front channels. The AI should reply within a few seconds. Then say *"I want to talk to a human"* — you should see a handoff note appear as an internal comment and the conversation unassigned.

    <Info>
      For channel-specific verification, see the [Channels](/integrations/front/channels/email) pages.
    </Info>
  </Step>
</Steps>

## Settings reference

All settings are configured at [**Settings → Ticketing System**](https://platform.open.cx/settings/ticketing) → Front.

| Setting | Purpose |
| - | - |
| **API token** | Your Front API token from Developer Settings. Required. |
| **AI teammate** | The Front teammate the AI replies as. Required for targeted routing. |
| **Handle unassigned conversations** | When enabled, the AI also responds to conversations with no assignee. Default: off. |
| **Enabled** | Master toggle for the Front integration. When disabled, all webhook events are ignored. |

## Disconnecting

To remove the Front integration, open [**Settings → Ticketing System**](https://platform.open.cx/settings/ticketing) → Front and click **Disconnect**. This deletes stored credentials, resets your ticketing system to OpenCX's built-in inbox, and stops webhook processing. Existing OpenCX sessions are preserved but no longer sync with Front.

***

## Related Documentation

<CardGroup>
  <Card title="Conversations" icon="messages" href="/integrations/front/conversations">
    How messages flow, handoff steps, and tags.
  </Card>

  <Card title="Knowledge Sync" icon="book" href="/knowledge/sources/front/connect">
    Train the AI on your Front Help Center articles.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/front/channels/email">
    Per-channel implementation details.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/front/troubleshooting">
    Credentials failing, webhook silent, AI not replying.
  </Card>
</CardGroup>


# Conversations
Source: https://docs.open.cx/integrations/front/conversations

How OpenCX processes Front conversations, hands off to your team, syncs tags, and resolves conversations.

Once your Front workspace is [connected](/integrations/front/connect), OpenCX listens for conversation events via webhook and processes them in real time. This page covers the shared flow that applies to every channel — see the [channel pages](/integrations/front/channels/email) for per-channel specifics.

## How conversations flow

```mermaid theme={"dark"}
flowchart LR
  A[Customer messages] --> B[Front webhook]
  B --> C[OpenCX AI]
  C --> D{Can resolve?}
  D -- Yes --> E[AI replies + archives]
  D -- No --> F[Handoff note + unassign]
  F --> G[Rep picks up in Front]
```

## What the AI listens for

OpenCX processes conversation events from the Front webhook:

| Event | What OpenCX does |
| - | - |
| **Inbound message** | Creates a session (or continues an existing one) and generates an AI reply. |
| **Outbound (teammate reply)** | Skipped to avoid duplicate processing. The AI does not respond to teammate-sent messages. |
| **Conversation archived** | Marks the OpenCX session as resolved and logs a history entry. |
| **Assignment changes** | Logged for debugging. No automatic state change. |
| **Tags added/removed** | Logged for debugging. No automatic state change. |

## Who the AI responds to

The AI processes a conversation only when one of these conditions is met:

1. The conversation is **assigned to the AI teammate** you selected during [setup](/integrations/front/connect).
2. The conversation is **unassigned** and **Handle unassigned conversations** is enabled.

Conversations assigned to other teammates are ignored — the AI does not interfere with your reps' work.

## Handoff to your team

When the AI decides it cannot resolve a conversation, it hands off in three steps:

<Steps>
  <Step title="Post an internal comment">
    OpenCX posts an internal comment to the Front conversation. The comment contains:

    * **Summary** of what the customer asked and the conversation so far.
    * **Sentiment** detected from the customer's messages (e.g. frustrated, neutral, positive).

    Your rep sees this immediately when they open the conversation.
  </Step>

  <Step title="Unassign the conversation">
    The AI teammate is removed from the conversation. The conversation enters your team's unassigned queue, where your routing rules or reps can pick it up.
  </Step>

  <Step title="Session stays open">
    The OpenCX session remains open so the human rep's replies are tracked. The conversation history stays intact for reporting and audit.
  </Step>
</Steps>

## AI resolution

When the AI fully resolves a conversation without needing human help:

<Steps>
  <Step title="Post a resolution note">
    OpenCX posts an internal comment with the resolution summary and sentiment.
  </Step>

  <Step title="Archive the conversation">
    The conversation is <Tooltip>archived</Tooltip> in Front. Your team can still find it in the archived view and reopen it if needed.
  </Step>
</Steps>

<Note>
  The AI only archives conversations it owns. If the conversation has been reassigned to a human rep, the AI checks the current assignee and skips the archive step.
</Note>

## Tags

OpenCX can sync session tags to Front conversations. Tags are created in Front if they don't already exist, then applied to the conversation.

Your team can use these tags to:

* Filter Front views by AI-handled conversations.
* Build analytics rules and reports.
* Route conversations based on AI-applied tags.

## Contact resolution

When a customer sends the first message, OpenCX resolves their identity:

1. The sender's handle (email address, phone number, or username) is extracted from the webhook payload.
2. OpenCX looks for an existing contact with a matching email.
3. If no match is found, a new contact is created with the sender's name and handle.

This ensures every conversation is linked to a contact for reporting and continuity across sessions.

## Deduplication

OpenCX deduplicates inbound messages by content hash with a 24-hour window. If Front retries a webhook delivery or sends a duplicate event, the second instance is silently dropped.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Front" icon="plug" href="/integrations/front/connect">
    API token, webhook, teammate selection, and settings.
  </Card>

  <Card title="Knowledge Sync" icon="book" href="/knowledge/sources/front/connect">
    Train the AI on your Front Help Center articles.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/front/channels/email">
    Per-channel details for Email, Chat, SMS, and Phone.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/front/troubleshooting">
    Handoff not firing, AI not replying, duplicate messages.
  </Card>
</CardGroup>


# Front overview
Source: https://docs.open.cx/integrations/front/overview

Run Front as the shared inbox your team works in while OpenCX resolves, routes, and hands off conversations with full context.

OpenCX works alongside your team inside Front. The AI resolves what it can, escalates what it can't, and posts a <Tooltip>handoff note</Tooltip> with full context straight into the conversation thread your reps already work in.

<Tip>
  Setup starts at [**Settings → Ticketing System**](https://platform.open.cx/settings/ticketing) in your OpenCX dashboard.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="Conversations your reps pick up with full context" icon="message">
    When the AI escalates, OpenCX posts an internal comment with a conversation summary and detected sentiment. The full AI-to-customer transcript is already in the Front thread — your rep reads one conversation, not two tools.
  </Accordion>

  <Accordion title="AI replies as a dedicated teammate" icon="robot">
    Choose a Front <Tooltip>teammate</Tooltip> to represent the AI. Customer-facing replies come from that account. Internal comments stay private. Your team always knows which messages the AI sent.
  </Accordion>

  <Accordion title="Unassigned conversations handled automatically" icon="circle-plus">
    Enable **Handle unassigned conversations** and the AI picks up conversations that arrive in your <Tooltip>inbox</Tooltip> without an assignee — no routing rules required.
  </Accordion>

  <Accordion title="Every channel your inbox receives" icon="grid-2">
    Email, SMS, chat, and phone conversations that land in Front are all processed by the AI. OpenCX maps each Front <Tooltip>message type</Tooltip> to the correct channel automatically.
  </Accordion>

  <Accordion title="Tags synced to your Front conversations" icon="tag">
    OpenCX creates and applies <Tooltip>tags</Tooltip> to Front conversations so your team can filter views and build reports without leaving Front.
  </Accordion>
</AccordionGroup>

## Supported channels

Pick the channel you want to wire through Front — each page covers the specifics for that channel on top of the shared setup.

<CardGroup>
  <Card title="Email" icon="envelope" href="/integrations/front/channels/email">
    Email conversations handed off to your Front inbox.
  </Card>

  <Card title="Chat" icon="comments" href="/integrations/front/channels/web">
    Web chat and messaging conversations routed to Front.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/integrations/front/channels/sms">
    Inbound SMS conversations handed off to your team.
  </Card>

  <Card title="Phone" icon="phone" href="/integrations/front/channels/phone">
    Call records handed off with the conversation context.
  </Card>
</CardGroup>

## Observability

Every conversation OpenCX touches in Front is traceable back to the exact OpenCX session. Your reps debug in the tool they already use; your admins audit without re-running the AI.

<AccordionGroup>
  <Accordion title="Handoff notes with AI reasoning" icon="note-sticky">
    Every handoff posts an <Tooltip>internal comment</Tooltip> containing the conversation summary and detected sentiment. Your rep opens the conversation and immediately knows **why** the AI escalated and **what** the customer needs.
  </Accordion>

  <Accordion title="Resolution notes on AI-closed conversations" icon="circle-check">
    When the AI resolves a conversation, it posts an internal comment with the resolution summary and sentiment, then <Tooltip>archives</Tooltip> the conversation in Front. Your team can review what was resolved and how.
  </Accordion>

  <Accordion title="Open in Front from your OpenCX Inbox" icon="link">
    Sessions linked to a Front conversation show an **Open in Front** button in the OpenCX [Inbox](https://platform.open.cx/inbox). One click opens the conversation directly in Front.
  </Accordion>

  <Accordion title="Tags you can filter views and reports by" icon="tag">
    OpenCX syncs session tags to Front conversations. Build Front views and analytics rules on these tags without touching OpenCX.
  </Accordion>
</AccordionGroup>

<Note>
  The **Open in Front** link appears automatically for any session that has a linked Front conversation. No extra configuration needed.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Front" icon="plug" href="/integrations/front/connect">
    API token, webhook, teammate selection, and settings.
  </Card>

  <Card title="Conversations" icon="messages" href="/integrations/front/conversations">
    How messages flow, handoff steps, and tags.
  </Card>

  <Card title="Knowledge Sync" icon="book" href="/knowledge/sources/front/connect">
    Train the AI on your Front Help Center articles.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/front/troubleshooting">
    Credentials failing, webhook silent, AI not replying.
  </Card>
</CardGroup>


# Front troubleshooting
Source: https://docs.open.cx/integrations/front/troubleshooting

Debug Front connection, webhook, handoff, and sync issues — 401 credential failures, missing AI replies, duplicate messages, broken escalations.

Before debugging, have this ready:

* Your Front <Tooltip>API token</Tooltip> and the <Tooltip>AI teammate</Tooltip> you selected.
* A specific <Tooltip>session ID</Tooltip> (from [Inbox](https://platform.open.cx/inbox)) or Front conversation ID where the problem shows.
* The webhook URL shown in [Settings → Ticketing System](https://platform.open.cx/settings/ticketing) → Front.

<Tip>
  Re-enter your credentials in [Settings → Ticketing System](https://platform.open.cx/settings/ticketing) → Front as your first step. Most issues are credential or webhook related.
</Tip>

<Info>
  **Fastest path to root cause:** find the conversation in your [OpenCX Inbox](https://platform.open.cx/inbox) and check the session's AI reasoning, tool calls, and handoff event. That's far faster than inspecting webhooks or logs.
</Info>

## Common scenarios

Jump to the symptom that matches what you're seeing.

### **"Invalid Front API token" on save**

<Tooltip>Likely cause</Tooltip>: token revoked, expired, or plan doesn't include API access.

**Fix:** regenerate the API token in Front's [Developer Settings](https://app.frontapp.com/settings/developers/tokens). Confirm the token has the required scopes (Shared Resources, Private Resources, Provisioning). Confirm your Front plan includes API access.

### **Webhook not receiving events**

<Tooltip>Likely cause</Tooltip>: webhook URL not configured in Front, or wrong event subscriptions.

**Fix:** open your Front app's webhook settings and confirm the webhook URL matches the one shown in [Settings → Ticketing System](https://platform.open.cx/settings/ticketing) → Front. Confirm the webhook is receiving inbound, outbound, and conversation archived events at minimum.

### **AI not responding to conversations**

<Tooltip>Likely cause</Tooltip>: conversation not assigned to AI teammate, integration disabled, or **Handle unassigned** is off.

**Fix:** check these in order:

1. Confirm the conversation is assigned to the teammate you selected as the AI teammate in [settings](/integrations/front/connect#settings-reference).
2. If the conversation is unassigned, confirm **Handle unassigned conversations** is enabled.
3. Confirm the integration is enabled (the master toggle is on).
4. Confirm the message is from a customer, not a teammate — the AI skips teammate-initiated and outbound messages.

### **Handoff posts a note but conversation stays assigned**

<Tooltip>Likely cause</Tooltip>: API error during unassign, or a concurrent Front rule reassigned the conversation.

**Fix:** this is usually transient. If it happens consistently, check whether a Front rule or automation is reassigning the conversation immediately after OpenCX unassigns it. Review the session in your [OpenCX Inbox](https://platform.open.cx/inbox) for error details.

### **Duplicate AI replies on the same message**

<Tooltip>Likely cause</Tooltip>: dedup window expired or concurrent webhook retries.

**Fix:** OpenCX deduplicates messages by content hash with a 24-hour window. If Front retries a webhook delivery after the window expires, a duplicate can occur. This is rare — if it happens consistently, confirm your Front webhook is not configured to retry aggressively.

### **AI archived a conversation that a rep was working on**

<Tooltip>Likely cause</Tooltip>: timing overlap between reassignment and AI resolution.

**Fix:** OpenCX checks the conversation assignee before archiving. If the conversation is no longer assigned to the AI teammate, the archive step is skipped. If this happened, the conversation can be reopened in Front. If it recurs, review your routing rules for timing conflicts.

### **Knowledge Sync not importing articles**

<Tooltip>Likely cause</Tooltip>: wrong API key, no Help Centers selected, or sync not started.

**Fix:** check these in order:

1. Go to [**Data Sources**](https://platform.open.cx/data-sources) and confirm the Front source shows a recent sync time.
2. Confirm the API key has read access to Help Center content.
3. Confirm at least one Help Center is selected.
4. Click **Sync now** to trigger a manual sync.

### **None of the above**

If your issue doesn't match any scenario above, gather the session ID from your [OpenCX Inbox](https://platform.open.cx/inbox) and the Front conversation ID, then contact support.

## Limits and timing

| | Value |
| - | - |
| **Message deduplication window** | 24 hours |
| **Webhook event processing** | Real-time (on delivery) |
| **AI teammate selection** | One per organization |
| **Teammate replies** | Skipped (not processed by AI) |
| **Archive on resolve** | Only if AI teammate is still assigned |

<Note>
  OpenCX retries on transient Front API failures but does not indefinitely retry. If your Front workspace is rate-limited or experiencing downtime, some webhook events may be missed. Check your Front webhook delivery logs for failed deliveries.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Front" icon="plug" href="/integrations/front/connect">
    Re-verify credentials and webhook setup.
  </Card>

  <Card title="Conversations" icon="messages" href="/integrations/front/conversations">
    How messages flow and how handoff works.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/front/channels/email">
    Per-channel details for Email, Chat, SMS, and Phone.
  </Card>

  <Card title="Handoff settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Connect Gorgias
Source: https://docs.open.cx/integrations/gorgias/connect

Enter your Gorgias API credentials, copy the webhook URL, and configure the default assignee for AI-processed tickets.

One-time setup: enter your Gorgias API key and domain, set a default assignee for handoffs, and paste the webhook URL into Gorgias so customer messages reach OpenCX.

<GorgiasFlow />

<Info>
  This page covers the Gorgias connection setup. Once connected, see [Ticket Flow](/integrations/gorgias/ticket-flow) for how messages are processed and handed off.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Gorgias account with API access" icon="key">
    You need a Gorgias helpdesk on a plan that includes REST API access. You also need admin permissions to create API keys and configure webhooks.
  </Accordion>

  <Accordion title="Admin access in OpenCX" icon="shield-check">
    Only organization admins can connect integrations. Confirm your role at [**Settings → Organization**](https://platform.open.cx/settings).
  </Accordion>

  <Accordion title="A dedicated Gorgias user for the AI" icon="user">
    The AI only processes tickets assigned to a specific Gorgias user. Create a dedicated user (e.g. "AI Agent") in Gorgias so your reps can distinguish AI-handled tickets from their own.
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Generate an API key in Gorgias">
    In your Gorgias helpdesk, go to **Settings → REST API** and create a new API key with full access.

    The API key is a Base64-encoded string combining your email and token. Gorgias shows this on the REST API page.

    <Warning>
      Store the API key securely — you will need it in the next step. If you lose it, revoke and regenerate from the same Gorgias settings page.
    </Warning>
  </Step>

  <Step title="Find your domain prefix">
    Your domain prefix is the subdomain of your Gorgias helpdesk URL. If your helpdesk is at `acme.gorgias.com`, the domain prefix is `acme`.
  </Step>

  <Step title="Find your default user ID">
    The default user ID is the Gorgias user the AI operates as. To find it:

    1. Go to **Settings → REST API** in Gorgias.
    2. Open the API explorer or use the `/users` endpoint.
    3. Find the user you created for the AI and note their numeric ID.

    <Note>
      The AI only processes tickets assigned to this user. Tickets assigned to anyone else are ignored — your human agents' work is never interrupted.
    </Note>
  </Step>

  <Step title="Enter credentials in OpenCX">
    Open [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard. Select **Gorgias** and enter:

    | Field | Value |
    | - | - |
    | **API Key** | The Base64-encoded API key from Gorgias Settings → REST API. |
    | **Domain Prefix** | Your Gorgias subdomain (e.g. `acme` from `acme.gorgias.com`). |
    | **Default User ID** | The numeric Gorgias user ID for the AI agent. |

    Click **Test & Save**. OpenCX validates the credentials by calling the Gorgias API. If validation fails, double-check that the API key has not been revoked and the domain prefix is correct.
  </Step>

  <Step title="Copy the webhook URL into Gorgias">
    After credentials are saved, OpenCX displays a webhook URL. Copy it and configure a webhook in Gorgias:

    1. In Gorgias, go to **Settings → Integrations → HTTP Integration** (or **Settings → Webhooks** depending on your Gorgias version).
    2. Create a new webhook with the URL you copied from OpenCX.
    3. Subscribe to **ticket message created** events so Gorgias notifies OpenCX when customers send messages.

    <Warning>
      Without the webhook, OpenCX cannot receive ticket messages. The AI will not respond to anything until the webhook is active and pointing to the correct URL.
    </Warning>
  </Step>

  <Step title="Send a test message">
    Create a test ticket in Gorgias (or have a customer send a message) assigned to your AI user. The AI should reply on the ticket within a few seconds.

    To test handoff, send a message like *"I want to talk to a human."* The ticket should be reassigned to your default user or team.
  </Step>
</Steps>

## Settings reference

All settings are configured at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) → Gorgias.

| Setting | Purpose | Required |
| - | - | - |
| **API Key** | Authenticates OpenCX with the Gorgias API. Base64-encoded. | Yes |
| **Domain Prefix** | Your Gorgias subdomain (e.g. `acme`). Determines the API endpoint. | Yes |
| **Default User ID** | The Gorgias user the AI operates as. Only tickets assigned to this user are processed. | Yes |

## Configure a Gorgias workflow for handoff routing

After setup, create a workflow rule in Gorgias to route handed-off tickets to your human agents. When the AI hands off, it reassigns the ticket to the configured default team. A Gorgias rule that triggers on team assignment can then route the ticket to the right agent.

<Info>
  Without a workflow rule, handed-off tickets stay in the default team's queue but are not automatically assigned to a specific agent. Your reps can still pick them up manually.
</Info>

## Disconnecting

To remove the Gorgias integration, open [**Settings → Integrations**](https://platform.open.cx/settings/integrations) → Gorgias and click **Disconnect** (or delete the saved credentials). This stops webhook processing. Existing OpenCX sessions are preserved but no longer receive updates from Gorgias.

<Note>
  Also remove the webhook URL from your Gorgias settings to stop Gorgias from sending events to an inactive endpoint.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Ticket Flow" icon="diagram-project" href="/integrations/gorgias/ticket-flow">
    How messages flow, handoff behavior, and what your reps see.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/gorgias/troubleshooting">
    Credentials failing, webhook silent, AI not replying.
  </Card>

  <Card title="Gorgias Overview" icon="cart-shopping" href="/integrations/gorgias/overview">
    What the integration does and supported channels.
  </Card>

  <Card title="Handoff Settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Gorgias overview
Source: https://docs.open.cx/integrations/gorgias/overview

Connect Gorgias as your ticketing system and let OpenCX AI resolve, reply, and hand off tickets to your e-commerce support team.

OpenCX connects to your Gorgias helpdesk and handles customer messages on tickets assigned to the AI. The AI reads the thread, generates a reply, and posts it back on the Gorgias ticket. When the AI cannot resolve, it hands the ticket off — your reps pick it up in Gorgias without switching tools.

<Tip>
  Setup starts at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="AI replies posted directly on your Gorgias tickets" icon="message">
    When a customer messages on a ticket assigned to the AI user, OpenCX processes the message through your trained AI and posts the response on the same Gorgias ticket. Your customers see a reply in whatever channel they used — email, chat, or social.
  </Accordion>

  <Accordion title="Handoff with configurable routing" icon="route">
    When the AI determines it cannot resolve, it marks the session as handed off and can reassign the ticket to a configured team. Pair this with a <Tooltip>Gorgias workflow rule</Tooltip> to route the ticket to the right agent.
  </Accordion>

  <Accordion title="Works across all Gorgias channels" icon="grid-2">
    The integration processes tickets regardless of how the customer reached you — email, live chat, social media, or phone. Every channel flows through the same webhook and AI pipeline in OpenCX. No per-channel setup required.
  </Accordion>

  <Accordion title="Duplicate message protection" icon="shield-check">
    OpenCX deduplicates incoming webhook events so the AI does not reply twice to the same customer message, even if Gorgias retries the webhook delivery.
  </Accordion>

  <Accordion title="Assignment-aware processing" icon="user-check">
    The AI only processes tickets assigned to the designated AI user in Gorgias. Tickets assigned to your human agents are left alone. Configure <Tooltip href="https://platform.open.cx/settings/autopilot">Autopilot</Tooltip> to fine-tune which topics the AI handles.
  </Accordion>
</AccordionGroup>

## Supported channels

The Gorgias integration handles tickets from every channel Gorgias supports. All channels flow through the same webhook and AI pipeline — there is no per-channel setup on the OpenCX side.

| Channel | How it works |
| - | - |
| **Email** | Customer emails create or update Gorgias tickets. The AI reply appears as a ticket response. |
| **Live chat** | Chat widget messages arrive as Gorgias tickets. The AI replies in the same thread. |
| **Social media** | Facebook, Instagram, and other social messages routed through Gorgias are processed the same way. |
| **Phone** | Voicemail transcriptions or phone-based tickets are processed as text messages. |

## Observability

<AccordionGroup>
  <Accordion title="Sessions linked to Gorgias ticket IDs" icon="link">
    Every Gorgias ticket that OpenCX processes is linked to an OpenCX session via the ticket ID. Find the session in your [Inbox](https://platform.open.cx/inbox) to see the full AI reasoning, tool calls, and handoff event.
  </Accordion>

  <Accordion title="Contact data from Gorgias" icon="address-book">
    OpenCX creates or matches a contact record using the customer's email and name from the Gorgias ticket. The same contact appears across sessions if the customer reaches out again.
  </Accordion>
</AccordionGroup>

## Get started

Enter your Gorgias API credentials, copy the webhook URL into Gorgias, and send a test message.

<Card title="Connect Gorgias" icon="plug" href="/integrations/gorgias/connect">
  API key, domain, webhook setup, and default assignee.
</Card>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Gorgias" icon="plug" href="/integrations/gorgias/connect">
    Credentials, webhook URL, and default assignee setup.
  </Card>

  <Card title="Ticket Flow" icon="diagram-project" href="/integrations/gorgias/ticket-flow">
    How messages flow, handoff behavior, and what your reps see.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/gorgias/troubleshooting">
    Credentials failing, webhook silent, AI not replying.
  </Card>

  <Card title="Handoff Settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Ticket Flow
Source: https://docs.open.cx/integrations/gorgias/ticket-flow

How OpenCX processes Gorgias tickets, replies to customers, and hands off to your team when the AI cannot resolve.

Once your Gorgias helpdesk is [connected](/integrations/gorgias/connect), OpenCX listens for customer messages via webhook and processes them in real time. This page covers how messages flow, when the AI replies, and what happens on handoff.

## How tickets flow

```mermaid theme={"dark"}
flowchart LR
  A[Customer messages on ticket] --> B[Gorgias webhook]
  B --> C[OpenCX AI]
  C --> D{Can resolve?}
  D -- Yes --> E[AI replies on ticket]
  D -- No --> F[AI replies + marks handoff]
  F --> G[Gorgias workflow routes to rep]
```

## What the AI listens for

OpenCX processes one type of Gorgias event: **customer messages on tickets assigned to the AI user**.

| Condition | What OpenCX does |
| - | - |
| **Customer sends a message** on a ticket assigned to the AI user | Creates or continues a session and generates an AI reply. |
| **Customer sends a message** on a ticket assigned to a different user | Ignores the message — the ticket belongs to a human agent. |
| **Agent replies** on a ticket | Not processed. Gorgias webhooks for agent messages are filtered out. |

<Note>
  OpenCX only processes messages where the sender email matches the customer email on the ticket. Internal notes and agent replies are ignored.
</Note>

## AI reply

When the AI generates a response, it posts the reply directly on the Gorgias ticket via the API. The reply appears as a message from **AI Assistant** (`ai@open.cx`), visible to the customer in whatever channel they used (email, chat, social).

<Note>
  AI replies are posted through the Gorgias REST API, not as the configured Gorgias user. The sender name in Gorgias shows "AI Assistant." To control how this appears to customers, configure your Gorgias email templates.
</Note>

## Handoff to your team

When the AI determines it cannot resolve a ticket, three things happen:

<Steps>
  <Step title="AI posts a final reply">
    The AI sends a response on the ticket — typically acknowledging the customer's request and letting them know a team member will follow up.
  </Step>

  <Step title="Session is marked as handed off">
    The OpenCX session state changes to handed off. The AI will not process further messages on this ticket, even if it remains assigned to the AI user.
  </Step>

  <Step title="Ticket is reassigned">
    OpenCX reassigns the ticket to the configured default user and team (if set) via the Gorgias API. If you configured a **default team**, the ticket moves into that team's view.
  </Step>
</Steps>

<Warning>
  **Set up a Gorgias workflow rule** to route handed-off tickets to the right agent. Since the AI stops processing after handoff, the ticket needs a human to pick it up. A Gorgias rule that triggers on assignment change or team change is the recommended approach.
</Warning>

## What the rep sees

* The ticket appears in their **Gorgias inbox** — routed there by your Gorgias workflow rule.
* The full AI-to-customer conversation is already in the ticket thread — no separate tool to check.
* The customer's email, name, and order context (if Gorgias has it) are on the ticket as usual.

## Good to know

<AccordionGroup>
  <Accordion title="Assignment-based processing" icon="user-check">
    The AI only touches tickets assigned to the default user ID you configured. If a ticket is assigned to anyone else — or is unassigned — OpenCX ignores it entirely. This prevents the AI from interfering with tickets your human agents are already working on.
  </Accordion>

  <Accordion title="Duplicate message protection" icon="shield-check">
    OpenCX deduplicates incoming messages using a content hash. If Gorgias delivers the same webhook event twice (e.g. due to a retry), the AI will not reply a second time. The deduplication window is 1 hour.
  </Accordion>

  <Accordion title="Session continuity across messages" icon="messages">
    All messages on the same Gorgias ticket map to the same OpenCX session. The AI sees the full conversation history when generating each reply, not just the latest message.
  </Accordion>

  <Accordion title="Reply format" icon="envelope">
    AI replies are posted via the Gorgias API as text messages from "AI Assistant" (`ai@open.cx`). On the Gorgias side, they appear as API-sourced messages. The customer receives them in whatever channel they originally used — the display format depends on your Gorgias email templates and channel settings.
  </Accordion>

  <Accordion title="After handoff, the AI stops" icon="circle-stop">
    Once a session is marked as handed off, the AI ignores all further messages on that ticket — even if the ticket remains assigned to the AI user in Gorgias. This prevents the AI from interfering after your team takes over.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Gorgias" icon="plug" href="/integrations/gorgias/connect">
    Credentials, webhook URL, and default assignee setup.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/gorgias/troubleshooting">
    Webhook not firing, AI not replying, handoff not reassigning.
  </Card>

  <Card title="Gorgias Overview" icon="cart-shopping" href="/integrations/gorgias/overview">
    What the integration does and supported channels.
  </Card>

  <Card title="Autopilot" icon="sliders" href="/handoff/topics">
    Configure which topics the AI handles and which it skips.
  </Card>
</CardGroup>


# Gorgias troubleshooting
Source: https://docs.open.cx/integrations/gorgias/troubleshooting

Debug Gorgias connection, webhook, AI reply, and handoff issues — 401 credential failures, silent ticket sync, duplicates, escalations that never fire.

Before debugging, have this ready:

* Your Gorgias <Tooltip>API key</Tooltip> and <Tooltip>domain prefix</Tooltip>.
* A specific <Tooltip>session ID</Tooltip> (from [Inbox](https://platform.open.cx/inbox)) or Gorgias ticket ID where the problem shows.
* The webhook URL shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Gorgias.

<Tip>
  Re-enter and click **Test & Save** in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Gorgias as your first step. Most issues are credential or webhook related.
</Tip>

<Info>
  **Fastest path to root cause:** find the session in your [OpenCX Inbox](https://platform.open.cx/inbox) and check the AI reasoning, tool calls, and handoff event. That is faster than inspecting webhooks or logs.
</Info>

## Common scenarios

Jump to the symptom that matches what you are seeing.

### **"Failed to save" or credentials rejected on save**

<Tooltip>Likely cause</Tooltip>: API key revoked, domain prefix wrong, or Gorgias plan does not include REST API access.

**Fix:** regenerate the API key in Gorgias under **Settings → REST API**. Confirm the domain prefix matches your Gorgias helpdesk URL (e.g. `acme` from `acme.gorgias.com`). Confirm your Gorgias plan includes API access.

### **Webhook not receiving events**

<Tooltip>Likely cause</Tooltip>: webhook URL not configured in Gorgias, wrong event subscriptions, or the webhook URL was changed after a credential update.

**Fix:** open your Gorgias webhook settings and confirm the URL matches the one shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Gorgias. Confirm the webhook is subscribed to **ticket message created** events. If you recently re-saved credentials, the webhook URL may have changed — copy the new one.

### **AI not responding to tickets**

<Tooltip>Likely cause</Tooltip>: ticket not assigned to the AI user, Autopilot disabled, or the message sender is not the customer.

**Fix:** check these in order:

1. Confirm the ticket is assigned to the Gorgias user ID you entered as the **Default User ID** in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Gorgias.
2. Confirm [Autopilot](https://platform.open.cx/settings/autopilot) is enabled.
3. Confirm the message was sent by the customer, not by an agent or an internal note.
4. Check the [Inbox](https://platform.open.cx/inbox) for the session — if a session exists, the webhook is working but the AI may have decided not to reply (check the AI reasoning).

### **Handoff fires but ticket is not routed to an agent**

<Tooltip>Likely cause</Tooltip>: no Gorgias workflow rule is configured to route tickets after handoff, or the default team ID is not set.

**Fix:** check these in order:

1. Confirm you have a Gorgias workflow rule that triggers when a ticket is assigned to your handoff team and routes it to the right agent.
2. If you are not using a default team, consider configuring one in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Gorgias (this requires re-saving settings via the API, as the dashboard currently exposes the user ID but not the team ID).
3. Check the [Inbox](https://platform.open.cx/inbox) for the session — the handoff event should be visible. If it is, the issue is on the Gorgias routing side.

### **Duplicate AI replies on the same message**

<Tooltip>Likely cause</Tooltip>: dedup window expired or webhook retried after the window.

**Fix:** OpenCX deduplicates messages by content hash with a 1-hour window. If Gorgias retries a webhook delivery after the window expires, a duplicate can occur. This is rare — if it happens consistently, check that your Gorgias webhook is not configured to retry aggressively.

### **AI replies appearing as the wrong user**

<Tooltip>Likely cause</Tooltip>: this is expected behavior. AI replies are posted through the Gorgias REST API and appear as API-sourced messages. The sender name is "AI Assistant."

**Fix:** this is not a bug. To control how the reply appears to customers, configure your Gorgias email templates and auto-reply settings.

### **AI keeps replying after handoff**

<Tooltip>Likely cause</Tooltip>: the session was not properly marked as handed off, or a new session was created for the same ticket.

**Fix:** check the session in [Inbox](https://platform.open.cx/inbox). If the session shows as handed off, the AI should not be replying. If you see a second session for the same ticket, the deduplication window may have expired (24-hour ticket lock). Contact [support](mailto:mo@open.cx) with the session ID.

### **None of the above**

If your issue does not match any scenario above, contact [support](mailto:mo@open.cx) with the Gorgias ticket ID, the OpenCX session ID (from [Inbox](https://platform.open.cx/inbox)), and a description of the expected vs actual behavior.

## Limits and timing

| | Value |
| - | - |
| **Message deduplication window** | 1 hour |
| **Ticket lock duration** | 24 hours |
| **Webhook token** | Signed per-organization, does not expire unless credentials are regenerated |

***

## Related Documentation

<CardGroup>
  <Card title="Connect Gorgias" icon="plug" href="/integrations/gorgias/connect">
    Re-verify credentials and webhook setup.
  </Card>

  <Card title="Ticket Flow" icon="diagram-project" href="/integrations/gorgias/ticket-flow">
    How messages flow and how handoff works.
  </Card>

  <Card title="Gorgias Overview" icon="cart-shopping" href="/integrations/gorgias/overview">
    What the integration does and supported channels.
  </Card>

  <Card title="Handoff Settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# AI Email Support
Source: https://docs.open.cx/integrations/hubspot/channels/email

Route email conversations into HubSpot as tickets and conversation threads with per-domain email signatures.

Email conversations route through HubSpot's conversations inbox. Every email handoff creates a HubSpot ticket and keeps the thread alive in HubSpot — your reps reply from HubSpot and the response lands in the customer's inbox with your branded signature attached.

## Pre-requisites

<Warning>
  **Set up email forwarding first.** No email handoff has anything to ticket until inbound mail is reaching OpenCX — start with [Connect Email](/email/forwarding) and come back here.
</Warning>

* **Email forwarding configured** — see [Connect Email](/email/forwarding).
* **HubSpot connected** — see [Connect HubSpot](/integrations/hubspot/connect).

## How conversations land in HubSpot

```mermaid theme={"dark"}
flowchart LR
  A[Customer emails your support address] --> B[AI replies from the same address]
  B --> C{AI can resolve?}
  C -- Yes --> D[Thread stays email-only]
  C -- No --> E[Handoff]
  E --> F[HubSpot ticket + conversation thread]
  F --> G[Rep replies — lands in customer inbox]
```

## Setting up

<Steps>
  <Step title="Confirm email forwarding works">
    Open [**Channels → AI Email**](https://platform.open.cx/channels/configure/mail) in the OpenCX dashboard. Your forwarding address should be listed and verified. Send a test email and confirm it reaches the [Inbox](https://platform.open.cx/inbox).
  </Step>

  <Step title="Confirm HubSpot is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **HubSpot**. The status should show the integration is connected, preferably via **OAuth Public App**.
  </Step>

  <Step title="Set up email signatures (optional)">
    If you want branded signatures on outgoing replies, configure them now. See [Email signatures](/integrations/hubspot/connect#email-signatures).
  </Step>

  <Step title="Trigger a test handoff">
    Send a test email to your connected address and respond with something that causes the AI to escalate. Or go to the [Inbox](https://platform.open.cx/inbox) and manually hand off the session.
  </Step>

  <Step title="Verify in HubSpot">
    A ticket should appear with the conversation summary and transcript, and an internal handoff comment should be posted on the associated conversation. Reply publicly from HubSpot and confirm:

    1. The reply arrives in the customer's email inbox.
    2. Your email signature is appended (if configured).
    3. The reply shows as an agent message in the [OpenCX Inbox](https://platform.open.cx/inbox).
  </Step>
</Steps>

## What the rep sees

* A **HubSpot ticket** with the conversation summary as the description.
* A **conversation thread** in the HubSpot inbox with the full AI-to-customer exchange.
* The contact's HubSpot record linked to the ticket (name, email, company, deals).
* An internal **handoff comment** with the AI's escalation reason, sentiment, and language.
* Public replies are delivered to the customer's inbox with the configured email signature.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Per-domain email signatures" icon="signature">
    Outgoing email replies through HubSpot automatically append the signature configured for the sender's email domain. Exact domain matches take priority over wildcard patterns. Set up signatures at [**Settings → Integrations → HubSpot**](https://platform.open.cx/settings/integrations) — see [Email signatures](/integrations/hubspot/connect#email-signatures).
  </Accordion>

  <Accordion title="HTML formatting preserved" icon="code">
    AI-generated replies are converted to HTML before sending through HubSpot's email channel. Formatting — bold, lists, links — renders correctly in the customer's email client.
  </Accordion>

  <Accordion title="Same thread reuses the ticket" icon="rotate">
    When a customer replies into the **same email thread** (HubSpot keeps it as one conversation), OpenCX reuses the existing session and its associated ticket — no duplicate ticket is created. A fresh thread from the same contact (new subject / new `Message-ID` chain) is treated as a new conversation and gets its own ticket.
  </Accordion>

  <Accordion title="Public vs internal replies" icon="eye">
    Only **public** replies from HubSpot are delivered to the customer. Internal comments stay private — they never reach the customer's inbox. Double-check you're posting on the **Reply** tab, not the **Comment** tab.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Email Support" icon="envelope" href="/email/introduction">
    The channel itself — forwarding setup, flow, troubleshooting.
  </Card>

  <Card title="Connect HubSpot" icon="plug" href="/integrations/hubspot/connect">
    OAuth setup, AI sender, email signatures.
  </Card>

  <Card title="HubSpot Overview" icon="hubspot" href="/integrations/hubspot/overview">
    What else HubSpot lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/hubspot/troubleshooting">
    Tickets not created, replies not syncing, signatures missing.
  </Card>
</CardGroup>


# HubSpot phone support and call follow-ups
Source: https://docs.open.cx/integrations/hubspot/channels/phone

Connect phone sessions to HubSpot tickets and configure callback tasks and call notes, with contact matching, outcome mapping, and verification.

Use HubSpot tickets for support handoff, and configure tasks and notes separately for callback appointments and call feedback. Connecting HubSpot does not automatically create all three for every phone attempt.

## Prerequisites

* A tested [AI phone agent](/phone/create-agent) and [outbound calling route](/phone/outbound-calls) if you will place callbacks.
* [HubSpot connected](/integrations/hubspot/connect) for native HubSpot workflow actions.
* Access to configure and activate workflows, and access to the destination HubSpot records.
* A reliable mapping between the OpenCX contact and the HubSpot contact. Their IDs are different; a phone number alone is not a HubSpot record ID.

## Create a HubSpot ticket from a phone session

Configure **Create HubSpot Ticket from Session** in the workflow that should create the support ticket. For a post-call workflow:

1. Choose **Call Finished** and filter the calls that require a support ticket. Do not add ticket creation to every outcome unless that is intentional.
2. Add **Create HubSpot Ticket from Session**.
3. Set **Session ID** from `trigger.call.ticket.ticketId` and choose the HubSpot pipeline and initial ticket status.
4. Set **Ticket Subject** and **Initial Comment** to explain the call result and requested next step. The final call summary may not yet be available.
5. Leave **Allow Multiple Tickets** off unless a new HubSpot ticket is required for the same session. Enable **Hand Off to a Human** only when the session should move to human handling; this changes ownership behavior and does not itself transfer phone audio.
6. Test the workflow, inspect its **HubSpot Ticket ID**, **Ticket URL**, and returned **Contact ID**, and verify the record in HubSpot.

For handoff during a live call, configure the appropriate handoff workflow and the agent's [transfer destination](/phone/agent-config#transfer-destinations). Ticket creation and moving the live caller are separate steps; verify both.

The action normally requires an identifiable contact. **Allow Without Contact** changes that requirement, but does not create a reliable customer association by itself. See [HubSpot handoff and sync](/integrations/hubspot/handoff) for the integration's support-session behavior.

## Callback tasks and call notes

Tasks and notes require an explicit CRM automation or API integration. The native **Create HubSpot Ticket from Session** action creates a ticket, not a callback task. **Send Webhook** can pass call fields to your integration endpoint; that endpoint needs its own HubSpot authorization and logic. It does not inherit the OpenCX HubSpot connection automatically.

### Pass the finished-call fields

In a **Call Finished** workflow, filter **Direction = Outbound**, then configure **Send Webhook** with your receiver's URL, `POST`, authentication headers, and these body parameters:

| Body key chosen for your receiver | Workflow value |
| - | - |
| `callId` | `trigger.call.callId` |
| `sessionId` | `trigger.call.ticket.ticketId` |
| `contactId` | `trigger.call.ticket.contact.id` |
| `outcome` | `trigger.call.outcome` |
| `disposition` | `trigger.call.disposition` |
| `endedAt` | `trigger.call.endTime` |
| `summary` | `trigger.call.summary` (possibly empty) |

These body keys define your receiver's input; they are not a built-in HubSpot action schema. Check **Is Success** and **Status Code** after sending. Your receiver should retain enough information to retry a CRM write without starting another phone call.

### Create and update activities

Your integration should resolve the HubSpot contact, then explicitly associate each activity with that record. For a callback task, use `POST /crm/v3/objects/tasks` with `hs_task_type: CALL`, `hs_task_subject`, `hs_task_status: NOT_STARTED`, the task owner when required, and `hs_timestamp` set to the agreed callback due time. Save the returned task ID. Rescheduling should update that task's due time; completion should update its status according to your business rule. See [HubSpot's task API](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/tasks/guide).

For call feedback, use `POST /crm/v3/objects/notes` with `hs_timestamp` set to the call event time and `hs_note_body` containing the outcome, disposition, call reference, and available feedback. Associate the note with the resolved HubSpot record and save its returned ID. See [HubSpot's notes API](https://developers.hubspot.com/docs/api-reference/legacy/crm/activities/notes/guide).

A HubSpot task is a reminder/activity record; creating it does not schedule the OpenCX dial. Configure the [callback workflow or external schedule](/phone/follow-up-workflows#schedule-one-callback-at-a-chosen-time) separately. Keep task updates and schedule cancellation/rescheduling coordinated in the system managing the appointment.

### Avoid duplicates and incomplete summaries

Store the OpenCX call ID with the HubSpot note ID so a repeated event updates or reuses the same activity. Store the callback appointment reference with the task ID so multiple dial attempts do not create duplicate appointment tasks. Route missing IDs or ambiguous contact matches for review.

**Call Finished can run before the final summary is generated.** Write the factual outcome first, then have a separate follow-up retrieve the completed session and update the same note when summary text is available. Do not interpret an empty summary as an integration failure, and do not mark a callback completed solely because dialing started.

## Verify before activation

Test with one contact you control:

* Confirm ticket, task, and note associations point to the correct HubSpot contact.
* Verify the callback due time in the customer's timezone and in the actual dial schedule.
* Trigger an answered call and an unanswered call; confirm each uses the intended outcome rule.
* Repeat delivery of a saved result and confirm no duplicate activity appears.
* Cancel or reschedule a callback and confirm both the HubSpot task and pending dial schedule reflect the change.
* Confirm delayed summary enrichment updates the existing note.

Use [Phone troubleshooting](/phone/troubleshooting) for calling problems and [HubSpot troubleshooting](/integrations/hubspot/troubleshooting) for connection or record-sync failures.


# AI SMS Support
Source: https://docs.open.cx/integrations/hubspot/channels/sms

File SMS handoffs as HubSpot tickets so your reps see the full conversation context.

When the AI hands off an SMS conversation, OpenCX creates a HubSpot ticket with the full transcript and customer context. Your reps see the ticket in HubSpot and follow up from there.

## Pre-requisites

<Warning>
  **Connect and verify your SMS number first.** No inbound SMS can reach OpenCX until the channel is live — start with [Connect SMS](/sms/connect-sms) and come back here.
</Warning>

* **SMS number connected and verified** — see [Connect SMS](/sms/connect-sms) and, for US numbers, [SMS compliance](/sms/compliance).
* **HubSpot connected** — see [Connect HubSpot](/integrations/hubspot/connect).

## How conversations land in HubSpot

```mermaid theme={"dark"}
flowchart LR
  A[Customer texts your SMS number] --> B[AI replies via SMS]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation closes]
  C -- No --> E[Handoff]
  E --> F[HubSpot ticket with transcript]
  F --> G[Rep follows up]
```

## Setting up

<Steps>
  <Step title="Confirm SMS is connected">
    Open [**Channels → SMS**](https://platform.open.cx/channels/sms) in the OpenCX dashboard. Your SMS number should be listed and active.
  </Step>

  <Step title="Confirm HubSpot is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **HubSpot**. The status should show the integration is connected, preferably via **OAuth Public App**.
  </Step>

  <Step title="Trigger a test handoff">
    Text your connected number and ask to speak to a human. The AI should hand off.
  </Step>

  <Step title="Verify in HubSpot">
    A ticket should appear with the SMS conversation summary and transcript, and an internal handoff comment should be posted with the AI summary, sentiment, and language. Confirm the contact's phone number is associated with the ticket.
  </Step>
</Steps>

## What the rep sees

* A **HubSpot ticket** with the conversation summary and full transcript.
* The contact's phone number and any prior HubSpot history linked to the ticket.
* An internal **handoff comment** with the AI's escalation reason, sentiment, and language.
* A link to the full OpenCX session for detailed AI reasoning and tool call history.

## Channel-specific details

<AccordionGroup>
  <Accordion title="US number compliance" icon="flag">
    US SMS numbers require <Tooltip>10DLC registration</Tooltip> or <Tooltip>toll-free verification</Tooltip> before they can reliably deliver outbound messages. Complete this on the OpenCX side — see [SMS compliance](/sms/compliance). The HubSpot integration doesn't change the requirement.
  </Accordion>

  <Accordion title="Message length and segmentation" icon="ruler">
    SMS messages are split into 160-character segments by carriers. The full conversation appears as one logical thread in the ticket transcript. Keep follow-up replies tight — carrier costs scale per segment.
  </Accordion>

  <Accordion title="Following up from HubSpot" icon="reply">
    HubSpot does not have a native two-way SMS conversation thread. To reply via SMS, use the [OpenCX inbox](https://platform.open.cx/inbox) or contact the customer directly. The HubSpot ticket provides visibility and tracking.
  </Accordion>

  <Accordion title="MMS" icon="image">
    Media sent by the customer (MMS) is included in the ticket context when the carrier supports it. Outbound MMS support depends on your SMS provider's capabilities.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI SMS Support" icon="comment-sms" href="/sms/introduction">
    The channel itself — connect, routing, compliance.
  </Card>

  <Card title="Connect HubSpot" icon="plug" href="/integrations/hubspot/connect">
    OAuth setup, AI sender, workflow actions.
  </Card>

  <Card title="HubSpot Overview" icon="hubspot" href="/integrations/hubspot/overview">
    What else HubSpot lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/hubspot/troubleshooting">
    Missing tickets, contact not linked.
  </Card>
</CardGroup>


# AI WhatsApp Support
Source: https://docs.open.cx/integrations/hubspot/channels/whatsapp

File WhatsApp handoffs as HubSpot tickets so your reps see the full conversation context.

When the AI hands off a WhatsApp conversation, OpenCX creates a HubSpot ticket with the full transcript and customer context. Your reps see the ticket in HubSpot and follow up from there.

## Pre-requisites

<Warning>
  **Connect your WhatsApp Business number first.** No WhatsApp messages can reach OpenCX until the channel is live — start with [Connect WhatsApp](/whatsapp/connect-whatsapp) and come back here.
</Warning>

* **WhatsApp Business number connected** — see [Connect WhatsApp](/whatsapp/connect-whatsapp).
* **HubSpot connected** — see [Connect HubSpot](/integrations/hubspot/connect).

## How conversations land in HubSpot

```mermaid theme={"dark"}
flowchart LR
  A[Customer messages your WhatsApp number] --> B[AI replies on WhatsApp]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation closes]
  C -- No --> E[Handoff]
  E --> F[HubSpot ticket with transcript]
  F --> G[Rep follows up]
```

## Setting up

<Steps>
  <Step title="Confirm WhatsApp is connected">
    Open [**Channels → WhatsApp**](https://platform.open.cx/channels/whatsapp) in the OpenCX dashboard. Your WhatsApp Business number should be listed and active.
  </Step>

  <Step title="Confirm HubSpot is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **HubSpot**. The status should show the integration is connected, preferably via **OAuth Public App**.
  </Step>

  <Step title="Trigger a test handoff">
    Send a WhatsApp message to your connected number and ask to speak to a human. The AI should hand off.
  </Step>

  <Step title="Verify in HubSpot">
    A ticket should appear with the WhatsApp conversation summary and transcript, and an internal handoff comment should be posted with the AI summary, sentiment, and language. Confirm the contact's phone number is associated with the ticket.
  </Step>
</Steps>

## What the rep sees

* A **HubSpot ticket** with the conversation summary and full transcript.
* The contact's phone number and any prior HubSpot history linked to the ticket.
* An internal **handoff comment** with the AI's escalation reason, sentiment, and language.
* A link to the full OpenCX session for detailed AI reasoning and tool call history.

## Channel-specific details

<AccordionGroup>
  <Accordion title="24-hour messaging window" icon="clock">
    WhatsApp limits free-form replies to 24 hours after the customer's last message. Outside that window, outbound messages require an approved <Tooltip>message template</Tooltip>. This constraint applies to follow-up from any channel, not just HubSpot.
  </Accordion>

  <Accordion title="Media messages" icon="image">
    Images, audio, and documents the customer sends on WhatsApp are included in the ticket as context. Size limits follow WhatsApp's per-media-type limits.
  </Accordion>

  <Accordion title="Following up from HubSpot" icon="reply">
    HubSpot does not have a native two-way WhatsApp conversation thread. To reply on WhatsApp, use the [OpenCX inbox](https://platform.open.cx/inbox) or contact the customer directly. The HubSpot ticket provides visibility and tracking.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI WhatsApp Support" icon="whatsapp" href="/whatsapp/introduction">
    The channel itself — connect, messaging rules, templates.
  </Card>

  <Card title="Connect HubSpot" icon="plug" href="/integrations/hubspot/connect">
    OAuth setup, AI sender, workflow actions.
  </Card>

  <Card title="HubSpot Overview" icon="hubspot" href="/integrations/hubspot/overview">
    What else HubSpot lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/hubspot/troubleshooting">
    Missing tickets, contact not linked.
  </Card>
</CardGroup>


# AI Chat Widget
Source: https://docs.open.cx/integrations/hubspot/channels/widget

Route web chat conversations from the AI Chat Widget into the HubSpot conversations inbox as live chats.

Widget conversations route through HubSpot's conversations inbox. When the AI hands off a chat, your rep picks it up as a live conversation in HubSpot — full transcript attached, no context lost.

## Pre-requisites

<Warning>
  **Install the AI Chat Widget on your site first.** HubSpot handoff has nothing to route until the widget is live — start with [Install Widget](/widget/install-widget) and come back here.
</Warning>

* **Widget installed and reachable** — see [Install Widget](/widget/install-widget).
* **HubSpot connected** — see [Connect HubSpot](/integrations/hubspot/connect).

## How conversations land in HubSpot

```mermaid theme={"dark"}
flowchart LR
  A[Visitor opens widget] --> B[AI answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Visitor closes the chat]
  C -- No --> E[Handoff]
  E --> F[HubSpot conversation + ticket]
  F --> G[Rep replies — lands in the widget]
```

## Setting up

<Steps>
  <Step title="Confirm the widget is live">
    Open the page where you embedded the widget and send a test message. The AI should respond. If the widget doesn't load, walk through [Install Widget](/widget/install-widget) first.
  </Step>

  <Step title="Confirm HubSpot is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **HubSpot**. The status should show the integration is connected, preferably via **OAuth Public App**.
  </Step>

  <Step title="Trigger a test handoff">
    Send a message like *"I want to talk to a human"* in the widget. The AI should hand off the conversation.
  </Step>

  <Step title="Verify in HubSpot">
    Open your HubSpot conversations inbox. The conversation should appear with the full AI transcript, and an internal handoff comment should be posted with the AI summary, sentiment, and language. A ticket is created alongside and associated with the conversation. Reply from HubSpot and confirm the message lands in the visitor's widget.
  </Step>
</Steps>

## What the rep sees

* A **conversation in the HubSpot inbox** with the full AI-to-visitor transcript.
* A **HubSpot ticket** associated with the conversation, carrying the conversation summary.
* The contact's details (name, email if provided, any prior history) linked to the conversation.
* An internal **handoff comment** with the AI's escalation reason, sentiment, and language.
* Replies typed in HubSpot land in the visitor's widget within a couple of seconds.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Authenticated vs anonymous visitors" icon="shield-check">
    When the widget passes a verified email via [widget authentication](/widget/authentication), OpenCX links the conversation to an existing HubSpot contact. Anonymous visitors get a new contact created from whatever information they provide during the chat.
  </Accordion>

  <Accordion title="File uploads" icon="paperclip">
    Files uploaded in the widget appear as attachments on the HubSpot conversation. File-size limits follow HubSpot's plan limits.
  </Accordion>

  <Accordion title="Widget custom components" icon="bolt">
    When an AI action returns data rendered by a [custom component](/widget/custom-components), the visitor sees the richer UI. Your rep sees the underlying text in HubSpot — write copy that reads well in both surfaces.
  </Accordion>

  <Accordion title="CSAT after the chat ends" icon="star">
    If your workflow triggers a satisfaction survey, the rating and comment land on the OpenCX session, not on a HubSpot feedback object.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Chat Widget" icon="messages" href="/widget/introduction">
    The channel itself — install, configure, authenticate.
  </Card>

  <Card title="Connect HubSpot" icon="plug" href="/integrations/hubspot/connect">
    OAuth setup, AI sender, workflow actions.
  </Card>

  <Card title="HubSpot Overview" icon="hubspot" href="/integrations/hubspot/overview">
    What else HubSpot lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/hubspot/troubleshooting">
    Widget handoff not appearing, missing rep replies.
  </Card>
</CardGroup>


# Connect HubSpot
Source: https://docs.open.cx/integrations/hubspot/connect

Connect HubSpot with the OpenCX OAuth Public App, select the HubSpot teammate the AI replies as, and verify sync end to end.

One-time setup to connect HubSpot to OpenCX. Use **OAuth Public App** unless your OpenCX admin tells you to use the legacy Private App path.

<HubspotFlow />

<Info>
  OAuth setup usually takes less than a minute. You need HubSpot admin access and OpenCX admin access.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="HubSpot account with Service Hub" icon="circle-check">
    The integration uses HubSpot's conversations and ticketing APIs. Service Hub (Starter or above) is required.
  </Accordion>

  <Accordion title="HubSpot admin access" icon="user-shield">
    You need permission to approve connected apps for the HubSpot portal you want OpenCX to use.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="key">
    Only organization owners and admins can save integration credentials in the OpenCX dashboard.
  </Accordion>
</AccordionGroup>

## What OAuth handles for you

The OAuth Public App replaces the manual Private App setup:

| | OAuth Public App |
| - | - |
| **Connection** | Approve OpenCX on HubSpot's consent screen |
| **Tokens** | Issued and refreshed automatically |
| **Webhooks** | Registered by OpenCX during install |
| **AI sender** | Picked from a HubSpot teammate dropdown after connect |
| **Workflow actions** | Adds OpenCX actions to HubSpot workflows |

## Setup

<Steps>
  <Step title="Open HubSpot integration settings">
    Open [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard and select **HubSpot**.

    The modal asks which connection method to use. Choose **OAuth Public App**.

    <Warning>
      If you already connected with a Private App, pick **OAuth Public App** to migrate. Existing tickets, sessions, and email signatures stay intact.
    </Warning>
  </Step>

  <Step title="Connect with HubSpot">
    Click **Connect with HubSpot**. OpenCX redirects you to HubSpot's consent screen.

    Choose the HubSpot portal to connect and approve the requested permissions.

    <Note>
      The permissions cover conversations, tickets, contacts, companies, deals, owners, files, lists, and HubSpot workflow actions. OpenCX requests them through HubSpot's standard app consent screen; you do not paste a token into OpenCX.
    </Note>
  </Step>

  <Step title="Confirm the connection in OpenCX">
    After approval, HubSpot redirects you back to **Settings → Integrations**. The HubSpot card shows **Connected**, and the modal shows **Connected via OAuth**.

    If the redirect shows an error, re-open the modal and try again. If HubSpot says the app is not available for the selected portal, confirm you are an admin for that portal.
  </Step>

  <Step title="Pick who the AI posts as">
    In the OAuth view, use **AI posts as** to select the HubSpot teammate OpenCX should attribute outgoing replies to.

    Customers see this teammate's name on email replies. Use a dedicated AI teammate if your team wants replies to be clearly labeled.
  </Step>

  <Step title="Enable Autopilot for the channel">
    Before testing, enable **Autopilot** for the channel you'll use in [**Settings → Autopilot**](https://platform.open.cx/settings/autopilot).

    Autopilot is configured per channel. If it is off for Email, Web, SMS, WhatsApp, or Phone, OpenCX stores the conversation but does not auto-reply on that channel.
  </Step>

  <Step title="Send a test message">
    For a HubSpot conversation to appear automatically, the conversation must originate from a channel HubSpot owns — either a HubSpot chat widget or an email address routed through a HubSpot inbox.

    1. Send a test email to a HubSpot-connected inbox, or send a message through the HubSpot chat widget.
    2. Confirm the conversation appears in HubSpot.
    3. Confirm a matching session appears in the [OpenCX inbox](https://platform.open.cx/inbox).
    4. Let the AI reply and confirm the reply posts back to the same HubSpot thread.
    5. Trigger a handoff and confirm the handoff note appears in HubSpot with a link back to the OpenCX session.
  </Step>
</Steps>

<Warning>
  The test above is for HubSpot-owned channels. OpenCX-native channels can still create HubSpot tickets on handoff through the `create-hubspot-ticket-from-session` workflow action; use the channel pages for verification steps.
</Warning>

## Workflow actions

OAuth installs add OpenCX actions to HubSpot workflows. Use them when HubSpot rules should control the AI:

| Action | Use it when |
| - | - |
| **Pause OpenCX AI** | A HubSpot workflow claims the conversation for a human. |
| **Resume OpenCX AI** | A workflow returns a handed-off conversation to the AI. |
| **Send to OpenCX AI** | A workflow decides the latest customer message should be processed by the AI. |
| **Request OpenCX handoff** | HubSpot should ask OpenCX to hand the session to a human. |

<Info>
  Workflow actions are available only on the OAuth Public App path. They do not appear for legacy Private App connections.
</Info>

## Email signatures

Append branded email signatures to outgoing replies sent through HubSpot. Signatures are matched to the sender's email domain, so different domains can have different signatures.

<Steps>
  <Step title="Open HubSpot settings">
    Go to [**Settings → Integrations → HubSpot**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard.
  </Step>

  <Step title="Add a signature">
    In the OAuth view, scroll to **Email Signatures** and click **Add**. Enter the domain pattern and paste your signature HTML.
  </Step>

  <Step title="Add more domains (optional)">
    Repeat for each domain that needs a different signature.
  </Step>
</Steps>

### Domain matching

| Pattern | Matches |
| - | - |
| `open.cx` | Emails from `open.cx` only (exact match) |
| `*.nl` | All emails ending with `.nl` (wildcard) |
| `*.co.uk` | All emails ending with `.co.uk` (wildcard) |

<Note>
  Exact domain matches always take priority over wildcard patterns. If you have both `open.cx` and `*.cx`, emails from `open.cx` use the exact-match signature.
</Note>

## Advanced: Private App (legacy)

Use **Private App (legacy)** only when OAuth is unavailable for your organization or support asks you to use the fallback path.

<AccordionGroup>
  <Accordion title="Create the Private App" icon="key">
    In HubSpot, go to **Settings → Integrations → Private Apps → Legacy Apps → Create Legacy App** and choose **Private**.

    Enable these scopes: `crm.objects.contacts.read`, `crm.objects.contacts.write`, `crm.objects.companies.read`, `crm.objects.deals.read`, `crm.objects.owners.read`, `tickets`, `conversations.read`, and `conversations.write`.

    Copy the **Private App Access Token** after creation. HubSpot shows it only once.
  </Accordion>

  <Accordion title="Configure the legacy webhook" icon="webhook">
    In OpenCX, choose **Private App (legacy)** and copy the **Webhook URL**.

    In HubSpot, paste that URL into the Private App's **Webhooks** tab, set event throttling high enough for your volume, and subscribe to:

    | Object type | Event |
    | - | - |
    | Conversation | New message |
    | Conversation | Conversation creation |
    | Ticket | Property change |

    Click **Commit changes** in HubSpot after editing subscriptions.
  </Accordion>

  <Accordion title="Save legacy credentials in OpenCX" icon="floppy-disk">
    In OpenCX, enter:

    | Field | Value |
    | - | - |
    | **Private App Access Token** | The `pat-...` token from HubSpot. |
    | **Default User ID** | The numeric HubSpot user ID only, with no `A-` prefix. |

    Find the user ID in HubSpot under **Settings → Users & Teams**. Open the teammate profile and copy the number at the end of the URL.
  </Accordion>
</AccordionGroup>

## Disconnecting

To disconnect an OAuth install, click **Disconnect** in [**Settings → Integrations → HubSpot**](https://platform.open.cx/settings/integrations), then type `DELETE` to confirm. Existing OpenCX sessions remain available.

If you use the legacy Private App path, also remove the webhook subscriptions from your HubSpot Legacy App.

***

## Related Documentation

<CardGroup>
  <Card title="Handoff & Sync" icon="arrow-right-arrow-left" href="/integrations/hubspot/handoff">
    Ticket creation, contact sync, CRM context.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/hubspot/troubleshooting">
    Connection failures, missing tickets, reply sync issues.
  </Card>

  <Card title="HubSpot Overview" icon="hubspot" href="/integrations/hubspot/overview">
    Capabilities, supported channels, observability.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    Global handoff settings and escalation rules.
  </Card>
</CardGroup>


# Handoff & Sync
Source: https://docs.open.cx/integrations/hubspot/handoff

How conversations move from AI to your HubSpot reps: ticket creation, contact sync, CRM context, and OAuth workflow actions.

After you [connect HubSpot](/integrations/hubspot/connect), this is what happens day-to-day when the AI escalates a conversation.

## How handoff lands in HubSpot

```mermaid theme={"dark"}
flowchart LR
  A[Customer message] --> B[AI replies]
  B --> C{AI can resolve?}
  C -- Yes --> D[Session closes]
  C -- No --> E[Handoff]
  E --> F[HubSpot ticket created]
  F --> G[Rep works the ticket]
```

When the AI decides to escalate:

1. **Contact lookup** — OpenCX searches HubSpot for a contact matching the customer's email. Creates one if none exists.
2. **Ticket created** — A HubSpot ticket is opened with the conversation summary and full transcript. The ticket is associated with the contact.
3. **Handoff comment** — An internal comment is posted on the HubSpot conversation with the AI's reason for escalating, detected sentiment, language, and a link back to the OpenCX session.
4. **Assignment** — The ticket is assigned to the default user configured during [setup](/integrations/hubspot/connect), or to a specific rep if your routing rules specify one.
5. **Custom data pushed** — Any custom data on the OpenCX session syncs to the ticket as HubSpot properties.

<Note>
  Ticket creation can be disabled per organization. When disabled, conversations still hand off but no HubSpot ticket is created. Contact your OpenCX admin to toggle this.
</Note>

## Rep replies sync back

For **web chat** and **email** channels, rep replies flow through HubSpot's conversations inbox and reach the customer on the same channel they wrote in. Internal comments stay private — only public replies are delivered.

For **WhatsApp**, **SMS**, and **phone** channels, HubSpot receives the ticket for visibility. Reps follow up through the [OpenCX inbox](https://platform.open.cx/inbox) or contact the customer directly.

## OAuth event behavior

OAuth installs register the HubSpot app webhook automatically. OpenCX acts on customer messages, ticket property changes, HubSpot agent replies, ownership changes, and help-desk notes. Unrecognized events are ignored.

**Conversation ownership matters.** If a HubSpot conversation is owned by a user other than your configured AI user, OpenCX stops replying. Reassign to the AI user to resume, or enable [Assist Mode](#assist-mode).

**Email has a 5-second delay** so other OpenCX workflows (drafting, signatures) finish first. Other channels process immediately.

<Card title="Webhook Reference" icon="webhook" href="/integrations/hubspot/webhooks">
  Full inbound envelope shape, per-event skip rules, and the HubSpot API calls OpenCX makes on handoff, reply, and close.
</Card>

## CRM context panel

When HubSpot is connected as a CRM, the OpenCX inbox shows the customer's HubSpot record on handoff:

* **Contact details** — name, email, phone number, contact owner
* **Company** — associated company name, domain, industry, size
* **Deals** — active and past deals with stage, amount, and close date
* **Previous tickets** — support history with subjects and status

<Note>
  The CRM context panel requires a separate connection at [**Settings → CRMs**](https://platform.open.cx/settings/crms). This is read-only access to HubSpot data — distinct from the ticketing integration at Settings → Integrations.
</Note>

## Contact sync

OpenCX keeps contacts in sync with HubSpot:

* **On first contact** — When a customer first writes in, OpenCX searches HubSpot by email. If found, the contact is linked. If not, a new HubSpot contact is created.
* **Custom data** — Ticket properties sync bidirectionally. Changes your reps make on the HubSpot ticket flow back to the OpenCX session, and custom data on the session pushes to the ticket.

OpenCX only syncs properties that exist in your HubSpot schema — invalid or missing fields are skipped silently.

## Sync custom statuses with ticket stages

You can map OpenCX custom statuses to HubSpot ticket pipeline stages so status changes stay aligned in both systems.

<Steps>
  <Step title="Sync HubSpot ticket stages">
    Open [**Settings → Custom Statuses**](https://platform.open.cx/settings/custom-statuses) and click **Sync from HubSpot**. The first successful sync enables stage mapping for your organization.
  </Step>

  <Step title="Verify automatic mappings">
    OpenCX links currently unmapped statuses when the trimmed names match and both represent the same open or closed state. It never creates new OpenCX statuses or replaces a manual mapping.
  </Step>

  <Step title="Correct mappings if needed">
    Use the **HubSpot Ticket Stage** column to select a stage grouped by pipeline, or choose **Not linked** to remove a link. Inactive stages remain visible on existing mappings but cannot be selected again.
  </Step>
</Steps>

<Warning>
  Applying a mapped custom status can move the HubSpot ticket to a different pipeline. Review manual mappings before using them on live sessions.
</Warning>

Changes flow in both directions: updating an OpenCX custom status moves the linked ticket to its mapped stage, while moving a HubSpot ticket to a mapped stage updates the OpenCX status. Unmapped or unavailable stages continue to use the pipeline's standard open or closed behavior.

## Assist mode

<Warning>
  **Assist Mode is a discouraged fallback.** We recommend [autopilot](/handoff/introduction) for every new deployment — Assist exists only for teams that aren't yet ready to hand customer replies to the AI.
</Warning>

When Assist Mode is enabled in [Autopilot](https://platform.open.cx/settings/autopilot) settings, the AI posts drafts as internal comments instead of replying publicly, leaves the conversation unassigned, and keeps tickets open for the rep to resolve.

## Good to know

<AccordionGroup>
  <Accordion title="Disabling ticket creation" icon="toggle-off">
    Ticket creation is on by default. Contact support if you need it disabled for your organization — conversations still hand off to reps in the OpenCX inbox, HubSpot just won't receive a ticket.
  </Accordion>

  <Accordion title="Tickets close on resolution" icon="circle-check">
    When an OpenCX session resolves, the associated HubSpot ticket is moved to the closed pipeline stage. The ticket summary and detected sentiment are added to the ticket content. Closing is delayed by \~15 seconds to stay within HubSpot API limits.

    This applies only when HubSpot is your ticketing system. If you connect HubSpot as a CRM and create tickets with the **Create HubSpot Ticket from Session** workflow action, closing the session leaves those tickets in their current stage for your HubSpot team to move.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Connect HubSpot" icon="plug" href="/integrations/hubspot/connect">
    OAuth setup, AI sender, workflow actions.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/hubspot/troubleshooting">
    Connection failures, missing tickets, reply sync issues.
  </Card>

  <Card title="Autopilot" icon="sliders" href="/handoff/topics">
    Control which topics the AI resolves vs escalates.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    Global handoff settings and escalation rules.
  </Card>
</CardGroup>


# Migrate to OAuth
Source: https://docs.open.cx/integrations/hubspot/oauth-migration

Switch HubSpot from a Private App access token to the OpenCX OAuth Public App without recreating tickets or signatures.

OpenCX now uses the HubSpot OAuth Public App for new HubSpot connections. If your organization still uses a Private App access token, migrate from the HubSpot integration modal.

## Why migrate

* **Private Apps are the legacy path.** New features such as workflow extensions only work on OAuth.
* **One click instead of token paste.** No more creating a HubSpot Private App, copying scopes, pasting access tokens, or configuring webhooks manually.
* **Better security.** OAuth tokens are short-lived and refreshed automatically. Private App tokens remain valid until rotated or revoked.
* **Faster agent takeover.** HubSpot ownership changes can pause the AI without waiting for the next customer message.

## What changes

| | Legacy Private App | OAuth Public App |
| - | - | - |
| Setup | Create app, paste token, configure webhooks | Approve OpenCX on HubSpot's consent screen |
| Access token | Paste-and-store | Issued and refreshed automatically |
| Webhook URL | Manually copied into HubSpot | Subscribed automatically on install |
| Workflow extensions in HubSpot | Not available | "Pause OpenCX AI", "Resume OpenCX AI", "Send to OpenCX AI", "Request OpenCX handoff" |
| Agent ownership changes | Slower fallback behavior | Processed by the OAuth app event path |

## How to migrate

1. In OpenCX, open **Settings → Integrations → HubSpot**.
2. Choose **OAuth Public App**. If your org is still on Private App auth, the modal shows an **Action recommended** banner.
3. Click **Connect with HubSpot**. HubSpot opens its consent screen.
4. Approve the requested permissions.
5. You'll bounce back to OpenCX with a "HubSpot connected" toast. The integration card now shows **Connected**.
6. **Optional:** in HubSpot, delete the OpenCX Private App you previously created. The new OAuth app supersedes it.

Your existing tickets, conversations, sessions, and email signature settings stay intact during the switch.

## Frequently asked questions

### Do I lose any tickets or conversation history during the switch?

No. The migration only touches the auth tokens. Your `chat_sessions`, `chat_history`, ticket links, and signature settings are untouched.

### What if I have multiple HubSpot portals?

OpenCX currently supports one HubSpot portal per OpenCX organization. Reconnecting via OAuth will use the portal of whoever clicks Connect.

### Can I roll back if something breaks?

Usually, yes. If your workspace still shows **Private App (legacy)**, you can reconnect with the previous token path. Some organizations are OAuth-only, so the legacy form may be hidden.

### What happens to the workflow actions if I'm on legacy?

Workflow actions only work on the OAuth path. Until you migrate, **Pause / Resume / Send-to-AI / Request handoff** won't appear inside HubSpot's Workflow builder for your portal.

***

## Related Documentation

<CardGroup>
  <Card title="Connect HubSpot" icon="plug" href="/integrations/hubspot/connect">
    OAuth setup and legacy fallback.
  </Card>

  <Card title="Handoff & Sync" icon="arrow-right-arrow-left" href="/integrations/hubspot/handoff">
    Day-to-day ticket and conversation behavior.
  </Card>

  <Card title="Webhook Reference" icon="webhook" href="/integrations/hubspot/webhooks">
    Events OpenCX receives and writes back.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/hubspot/troubleshooting">
    Reconnect prompts and sync issues.
  </Card>
</CardGroup>


# HubSpot overview
Source: https://docs.open.cx/integrations/hubspot/overview

Run HubSpot as the surface your reps work in while OpenCX resolves, routes, and syncs every conversation and customer record.

OpenCX works alongside your reps inside HubSpot. The AI resolves what it can, escalates what it can't, and files every <Tooltip>handoff</Tooltip> straight into a HubSpot ticket or conversation thread your reps already live in — no separate inbox, no context rebuild.

<Note>
  This page covers **HubSpot as a control integration** — tickets, handoff, conversations, and CRM context. For **syncing Knowledge Base articles as AI training data**, see [HubSpot as a knowledge source](/knowledge/sources/hubspot-kb/overview).
</Note>

<Tip>
  Setup starts at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard. Use **OAuth Public App** for new connections.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="Tickets your reps pick up with full context" icon="ticket">
    When the AI escalates, OpenCX creates a HubSpot ticket. The conversation summary becomes the description, the full transcript is attached, and an internal handoff comment lands on the conversation with the AI's reasoning. Your reps open the ticket and keep going — no "what happened before I got here?" questions.
  </Accordion>

  <Accordion title="Conversations that stay in HubSpot end to end" icon="reply">
    Web chat and email conversations flow through HubSpot's conversations inbox. Rep replies travel back to the contact on the channel they wrote in. Internal comments stay private.
  </Accordion>

  <Accordion title="CRM context when your reps need it" icon="address-book">
    On handoff, the OpenCX inbox displays the contact's HubSpot record — name, email, company, deals, and previous tickets. Your reps see the full customer picture without switching tabs.
  </Accordion>

  <Accordion title="Contact data stays in sync" icon="rotate">
    OpenCX creates or updates HubSpot contacts automatically. Custom data on tickets syncs both directions — changes your reps make in HubSpot flow back to the OpenCX session, and vice versa.
  </Accordion>
</AccordionGroup>

## Supported channels

Pick the channel you want to wire through HubSpot — each page covers the implementation details for that channel on top of the shared HubSpot setup.

<CardGroup>
  <Card title="AI Chat Widget" icon="comments" href="/integrations/hubspot/channels/widget">
    Live chat handoff into the HubSpot conversations inbox.
  </Card>

  <Card title="AI Email Support" icon="envelope" href="/integrations/hubspot/channels/email">
    Email threads routed to HubSpot with per-domain signatures.
  </Card>

  <Card title="AI WhatsApp Support" icon="whatsapp" href="/integrations/hubspot/channels/whatsapp">
    WhatsApp handoffs filed as HubSpot tickets with full context.
  </Card>

  <Card title="AI SMS Support" icon="comment-sms" href="/integrations/hubspot/channels/sms">
    SMS handoffs filed as HubSpot tickets.
  </Card>

  <Card title="AI Phone Support" icon="phone" href="/integrations/hubspot/channels/phone">
    Phone handoffs with call transcript attached to the ticket.
  </Card>
</CardGroup>

## Observability

<AccordionGroup>
  <Accordion title="Handoff comment with summary and sentiment" icon="clipboard-list">
    Every handoff posts an internal comment on the HubSpot conversation with the AI's summary of the issue, detected sentiment, and language. Your reps know why the AI escalated before they read the transcript.
  </Accordion>

  <Accordion title="Session link back to OpenCX" icon="link">
    The handoff comment includes a direct link to the full OpenCX session — AI reasoning, tool calls, and the complete conversation timeline. One click from HubSpot to the debug view.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Connect HubSpot" icon="plug" href="/integrations/hubspot/connect">
    OAuth setup, AI sender, workflow actions, signatures.
  </Card>

  <Card title="Handoff & Sync" icon="arrow-right-arrow-left" href="/integrations/hubspot/handoff">
    Ticket creation, contact sync, CRM context.
  </Card>

  <Card title="Webhook Reference" icon="webhook" href="/integrations/hubspot/webhooks">
    Inbound event payloads and the HubSpot API calls OpenCX makes back.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/hubspot/troubleshooting">
    Connection failures, missing tickets, reply sync issues.
  </Card>
</CardGroup>


# HubSpot troubleshooting
Source: https://docs.open.cx/integrations/hubspot/troubleshooting

Debug HubSpot OAuth, reconnect prompts, ticket creation, reply sync, and legacy Private App issues.

Before debugging, have this ready:

* **Connection method** — is HubSpot connected with **OAuth Public App** or **Private App (legacy)** in [Settings → Integrations](https://platform.open.cx/settings/integrations)?
* **Session ID** — find it in the [OpenCX inbox](https://platform.open.cx/inbox) for the conversation in question.
* **HubSpot conversation or ticket link** — open the exact thread your rep is testing.

<Tip>
  If the modal says **Reconnect required**, reconnect with **OAuth Public App** first. HubSpot may have rejected the refresh token after the app was removed or permissions changed.
</Tip>

## Common scenarios

### **OAuth connect or reconnect fails**

<Tooltip>Likely cause</Tooltip>: wrong HubSpot portal, missing HubSpot admin access, canceled consent, or revoked app install.

**Fix:**

1. In OpenCX, open [**Settings → Integrations → HubSpot**](https://platform.open.cx/settings/integrations).
2. Choose **OAuth Public App** and click **Connect with HubSpot** or **Reconnect**.
3. In HubSpot, confirm you are approving the correct portal.
4. If HubSpot blocks the install, ask a HubSpot super admin to approve connected apps for the portal.
5. If the redirect lands back on an error toast, retry once and share the error text with OpenCX support.

### **Private App token save fails**

<Tooltip>Likely cause</Tooltip>: expired or revoked Private App token, wrong token format, or missing scopes.

**Fix:**

1. Use OAuth if your workspace allows it; the Private App path is legacy.
2. If you must use legacy, confirm the token starts with `pat-`.
3. Confirm the Private App includes the scopes listed in [Advanced: Private App (legacy)](/integrations/hubspot/connect#advanced-private-app-legacy).
4. Paste the token into **Private App Access Token**, enter the numeric **Default User ID**, and save.

### **Handoff runs but no ticket appears**

<Tooltip>Likely cause</Tooltip>: the conversation didn't originate from a channel HubSpot owns (most common), ticket creation is disabled, or the contact has no email for HubSpot to match.

**Fix:**

1. **Check the channel.** Tickets appear automatically only when the conversation starts from a channel HubSpot owns — a HubSpot chat widget, or an email routed through a HubSpot inbox. Messages sent to OpenCX's `temporary+...@instant.cx` address never reach HubSpot, so no ticket is created.
2. **For non-HubSpot channels** (OpenCX email, widget, WhatsApp, SMS, phone), use the `create-hubspot-ticket-from-session` workflow action on handoff.
3. Check with your OpenCX admin whether ticket creation is enabled for HubSpot.
4. Confirm the contact in the OpenCX session has an email address — HubSpot needs it to associate the ticket with a contact.
5. If all of the above are correct, check that the webhook is still registered in HubSpot (see below).

### **Rep replies don't reach the customer**

<Tooltip>Likely cause</Tooltip>: webhook not registered in HubSpot, wrong event subscriptions, uncommitted subscription changes, or stale webhook URL.

**Fix:**

1. Confirm HubSpot still shows **Connected via OAuth** in OpenCX. Reconnect if the modal shows **Reconnect required**.
2. Confirm the rep replied **publicly**, not as an internal note. Internal notes sync to OpenCX as private agent comments and are not delivered to customers.
3. If you use the legacy Private App path, confirm the webhook subscriptions are committed in HubSpot and the target URL matches the URL shown in OpenCX.
4. Check the customer's channel is still reachable (email valid, widget session open, phone number active).

### **AI stopped replying mid-thread**

<Tooltip>Likely cause</Tooltip>: the conversation owner is not the configured AI user.

**Fix:**

1. In HubSpot, open the conversation and check the **Assigned to** field.
2. Reassign to the user whose ID you configured as the **Default User ID** in OpenCX.
3. If you want the AI to keep drafting while reps own the conversation, enable [Assist Mode](https://platform.open.cx/settings/autopilot) instead.

### **Legacy webhook shows delivered in HubSpot but nothing happens**

<Tooltip>Likely cause</Tooltip>: the webhook URL in HubSpot is stale or was copied from a different org.

**Fix:**

1. In OpenCX, choose **Private App (legacy)** and re-copy the webhook URL.
2. In HubSpot, open your Legacy App (**Settings → Integrations → Private Apps → Legacy Apps**) → **Webhooks** and replace the target URL.
3. Trigger a test conversation to confirm events are now processed.

### **Email reaches HubSpot, threads appear, but no OpenCX session is created**

<Tooltip>Likely cause</Tooltip>: the legacy Private App is missing the `crm.objects.owners.read` scope.

**How to confirm:**

1. In HubSpot, open your Legacy App → **Monitoring** → **API Calls**.
2. Look for `GET /crm/owners/v3/A-<number>` returning **403** with `MISSING_SCOPES` in the error body. This is the exact failure.

**Fix:**

1. Legacy App → **Scopes** tab → enable `crm.objects.owners.read`, or migrate to OAuth.
2. Click **Save** / commit scope changes.
3. In OpenCX [Settings → Integrations → HubSpot](https://platform.open.cx/settings/integrations), re-save to refresh the cached client.
4. Send a fresh test email and confirm the session now appears in the [OpenCX inbox](https://platform.open.cx/inbox).

### **CRM context panel is empty**

<Tooltip>Likely cause</Tooltip>: CRM integration not connected, or the contact's email doesn't match any HubSpot record.

**Fix:**

1. The CRM context panel is configured at [**Settings → CRMs**](https://platform.open.cx/settings/crms) — this is a separate connection from Settings → Integrations.
2. Confirm the contact's email in OpenCX matches a contact in your HubSpot portal.
3. Test the CRM connection from Settings → CRMs.

<Info>
  OpenCX returns 200 OK to HubSpot webhooks immediately and processes them in the background. A successful webhook delivery in HubSpot's logs does not guarantee processing succeeded on the OpenCX side.
</Info>

## Replies not syncing: full checklist

If handoff creates a ticket but replies do nothing:

1. Confirm the ticket has a handoff comment posted on the associated HubSpot conversation (AI summary, sentiment, language, OpenCX session link).
2. Confirm HubSpot is connected via OAuth, or re-check legacy webhook subscriptions if you are still on Private App auth.
3. Confirm the reply was sent as a **public** message, not an internal note.
4. Check the customer's channel is still reachable (email valid, phone active, widget session open).
5. Confirm Autopilot or Assist Mode settings match the behavior you expect for that channel.

## Limits & timing

| | Value |
| - | - |
| **Webhook processing** | Returns 200 OK immediately, async processing |
| **Event delivery** | At-most-once — failures are logged, not retried |
| **OAuth tokens** | Refreshed automatically; reconnect required if HubSpot revokes the install |
| **OAuth webhook setup** | Registered automatically during install |
| **Ticket close delay** | \~15 seconds before closing tickets on resolution |
| **Transient failure retry** | HubSpot API calls retry up to 3 times on error |
| **Contact creation failure** | Non-blocking — handoff proceeds even if the HubSpot contact can't be created |
| **Email channel delay** | \~5 seconds on email events to let concurrent workflows finish |

<Note>
  OpenCX retries transient HubSpot API failures automatically but does not retry indefinitely past rate limits. If tickets are not appearing during a high-volume period, wait a few minutes and check again.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect HubSpot" icon="plug" href="/integrations/hubspot/connect">
    Re-check OAuth, AI sender, legacy fallback.
  </Card>

  <Card title="Handoff & Sync" icon="arrow-right-arrow-left" href="/integrations/hubspot/handoff">
    Re-check handoff behavior, ticket creation, and contact sync.
  </Card>

  <Card title="Webhook Reference" icon="webhook" href="/integrations/hubspot/webhooks">
    Event payloads, skip rules, and outbound HubSpot API calls.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    Global handoff settings and escalation rules.
  </Card>
</CardGroup>


# Webhook Reference
Source: https://docs.open.cx/integrations/hubspot/webhooks

HubSpot events OpenCX receives through the OAuth app and the HubSpot API calls OpenCX makes on handoff, reply, and close.

Inbound events HubSpot sends to OpenCX through the HubSpot app, plus the HubSpot API calls OpenCX makes back out. Shapes match the current implementation.

<Info>
  OAuth installs configure webhook delivery automatically. The legacy Private App path still uses an organization-specific webhook URL you copy from OpenCX.
</Info>

<Tabs>
  <Tab title="Inbound (HubSpot to OpenCX)">
    HubSpot POSTs an array of events to OpenCX. OpenCX returns `200 OK` immediately and processes in the background.

    <CodeGroup>
      ```json Envelope theme={"dark"}
      [
        {
          "eventId": 1234567890,
          "subscriptionId": 987654,
          "portalId": 12345678,
          "appId": 2345678,
          "occurredAt": 1713790000000,
          "subscriptionType": "conversation.newMessage",
          "attemptNumber": 0,
          "objectId": "9598272090",
          "changeSource": "CRM",

          "messageId": "abc-123",
          "messageType": "MESSAGE",
          "changeFlag": "NEW_MESSAGE",

          "propertyName": "hs_pipeline_stage",
          "propertyValue": "2"
        }
      ]
      ```
    </CodeGroup>

    <ParamField type="string">
      Event type. OpenCX acts on supported HubSpot conversation, ticket, and note events. Everything else is ignored.
    </ParamField>

    <ParamField type="string">
      Thread ID (conversation events) or ticket ID (ticket events).
    </ParamField>

    <ParamField type="string">
      On conversation events, OpenCX re-fetches the message via `GET /conversations/v3/conversations/threads/{threadId}/messages/{messageId}` — the webhook envelope does **not** carry the message body.
    </ParamField>

    <ParamField type="'MESSAGE' | 'COMMENT'">
      `COMMENT` events are skipped (internal notes aren't customer messages).
    </ParamField>

    <ParamField type="string">
      Set on `ticket.propertyChange`. Empty values are ignored.
    </ParamField>

    <AccordionGroup>
      <Accordion title="conversation.newMessage" icon="message">
        Re-fetches the message from HubSpot, then routes it through the AI if it passes filters.

        **Skipped when:** the sender is automated, a bot, or OpenCX's own AI marker. HubSpot agent replies and internal notes are stored on the OpenCX session instead of being sent back to the AI.

        **Email only:** a 5-second delay lets other OpenCX workflows (drafting, signatures) finish first.

        **Dedup key:** message ID, scoped to the OpenCX organization.
      </Accordion>

      <Accordion title="conversation.propertyChange" icon="user-gear">
        Handles ownership changes. If the conversation is assigned away from the configured AI user, OpenCX marks the session as handed off unless Assist Mode is enabled.
      </Accordion>

      <Accordion title="ticket.propertyChange" icon="pen-to-square">
        Syncs the changed property onto the associated OpenCX session's custom data.

        **Skipped when:** ticketing is disabled in settings, or `propertyValue` is null / empty string.
      </Accordion>

      <Accordion title="object.creation for help-desk notes" icon="note-sticky">
        Mirrors HubSpot help-desk notes attached to a synced ticket into the OpenCX timeline as internal agent comments.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Outbound (OpenCX to HubSpot)">
    On handoff and during the session lifecycle, OpenCX writes back to HubSpot through the OAuth connection.

    <AccordionGroup>
      <Accordion title="Find or create contact" icon="user">
        Looks up the contact by email before creating a ticket. Creates one if missing.

        ```http theme={"dark"}
        POST /crm/v3/objects/contacts/search
        POST /crm/v3/objects/contacts
        ```
      </Accordion>

      <Accordion title="Create handoff ticket" icon="ticket">
        Opens a ticket associated with the contact. Subject, content (conversation summary), pipeline/stage, priority, owner, and any session `custom_data` / `editable_custom_data` are written as ticket properties.

        ```http theme={"dark"}
        POST /crm/v3/objects/tickets
        ```
      </Accordion>

      <Accordion title="Post handoff comment" icon="clipboard-list">
        Posts an internal `COMMENT` on the HubSpot conversation thread with the AI summary, sentiment, language, and a link back to the OpenCX session.

        ```http theme={"dark"}
        POST /conversations/v3/conversations/threads/{threadId}/messages
        ```
      </Accordion>

      <Accordion title="Reply to customer" icon="reply">
        AI and agent-assist drafts are posted as public `MESSAGE` on the same conversation thread — email replies get the matching domain signature appended.

        ```http theme={"dark"}
        POST /conversations/v3/conversations/threads/{threadId}/messages
        ```
      </Accordion>

      <Accordion title="Close ticket on resolution" icon="circle-check">
        When the OpenCX session resolves, the associated ticket is moved to the pipeline's closed stage. Delayed \~15s to stay within rate limits.

        ```http theme={"dark"}
        PATCH /crm/v3/objects/tickets/{ticketId}
        ```
      </Accordion>
    </AccordionGroup>

    <Note>
      Transient HubSpot API errors retry up to 3 times. Contact creation failures are non-blocking — handoff still proceeds. OpenCX only writes properties that exist in your HubSpot schema; unknown fields are skipped silently.
    </Note>
  </Tab>
</Tabs>

***

## Related Documentation

<CardGroup>
  <Card title="Connect HubSpot" icon="plug" href="/integrations/hubspot/connect">
    OAuth setup, AI sender, workflow actions.
  </Card>

  <Card title="Handoff & Sync" icon="arrow-right-arrow-left" href="/integrations/hubspot/handoff">
    Day-to-day handoff flow, rep replies, CRM context, contact sync.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/hubspot/troubleshooting">
    Connection, webhook, ticket, and reply sync debugging.
  </Card>

  <Card title="HubSpot Overview" icon="hubspot" href="/integrations/hubspot/overview">
    Capabilities and supported channels.
  </Card>
</CardGroup>


# Connect Infobip
Source: https://docs.open.cx/integrations/infobip/connect

Create an Infobip API key with the conversations:manage scope, pick your AI agent, and register the OpenCX webhook as a subscription.

The Infobip integration uses an <Tooltip>Infobip API key</Tooltip> to read and write conversations, plus a webhook subscription you register in the Infobip portal that pushes conversation events to OpenCX.

<Info>
  Setup takes about 10 minutes. You need admin access in both the Infobip portal
  and your OpenCX organization.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="A dedicated AI agent in Infobip" icon="user-headset">
    The AI replies as an Infobip agent you designate, and only answers conversations assigned to that agent. Create a dedicated agent (for example *OpenCX AI*) in the Infobip Conversations dashboard rather than reusing a person's account.
  </Accordion>

  <Accordion title="Permission to create API keys and subscriptions" icon="key">
    You'll create an API key under **Developer Tools → API Keys** and a
    subscription that delivers conversation events — both need Infobip admin
    access.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="user-shield">
    Required to save integration settings in [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Find your Base URL">
    Log in to Infobip and open any API documentation page — your account-specific base URL is shown at the top. It looks like `https://abc123.api.infobip.com`.
  </Step>

  <Step title="Create an API key">
    In the Infobip portal, go to [**Developer Tools → API Keys**](https://portal.infobip.com/dev/api-keys/create) and create a key with the **conversations:manage** scope (under the Customer Engagement section).

    <Warning>
      Copy the key immediately — Infobip only shows it at creation.
    </Warning>
  </Step>

  <Step title="Enter your credentials in OpenCX">
    In your OpenCX dashboard, go to [**Settings → Integrations**](https://platform.open.cx/settings/integrations), select **Infobip**, and fill in:

    | Field | Value |
    | - | - |
    | **Base URL** | Your account-specific URL, e.g. `https://abc123.api.infobip.com`. |
    | **API Key** | The key you just created. |

    Click **Connect**. OpenCX validates the credentials against the Infobip API before saving.
  </Step>

  <Step title="Pick the AI agent">
    After connecting, the **AI Agent** dropdown loads the agents from your Infobip workspace. Pick the dedicated agent the AI should reply as.

    The AI only answers conversations **assigned to this agent**. Two toggles refine the behavior:

    | Toggle | Default | What it does |
    | - | - | - |
    | **Handle unassigned conversations** | Off | When on, the AI also picks up conversations with no assignee — it assigns them to the AI agent, then replies. Turn this on when the AI is your front door. |
    | **Close Infobip conversation when resolved** | On | When the AI resolves a session, OpenCX also closes the Infobip conversation and posts a resolution note. |
  </Step>

  <Step title="Register the webhook subscription in Infobip">
    Copy the **Webhook URL** shown at the top of the OpenCX Infobip settings. Then, in the Infobip portal, create a [subscription](https://www.infobip.com/docs/cpaas-x/subscriptions-management) with that URL as the **receiver**, covering conversation events (inbound and outbound messages, status, assignment, and note events).

    <Warning>
      The webhook URL contains a signed token tied to your organization — treat it like a password. And without the subscription, no events reach OpenCX and the AI stays silent: this manual step is the one most often missed.
    </Warning>
  </Step>

  <Step title="Send a test message">
    Write in on any connected channel (for example your WhatsApp number). Assign the conversation to the AI agent — or just send, if **Handle unassigned conversations** is on. Within a few seconds:

    1. A new session appears in your [OpenCX Inbox](https://platform.open.cx/inbox).
    2. The AI's reply appears in the Infobip conversation as your AI agent, on the same channel.

    If nothing appears, jump to [Troubleshooting](/integrations/infobip/troubleshooting).
  </Step>
</Steps>

## Disconnecting

In OpenCX, open the Infobip integration and disconnect it. Then delete the subscription in the Infobip portal. Conversations already exchanged stay in your OpenCX inbox; no new Infobip events flow in, and the AI stops replying.

***

## Related Documentation

<CardGroup>
  <Card title="Overview" icon="comments" href="/integrations/infobip/overview">
    What the Infobip integration does and how messages flow.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/infobip/troubleshooting">
    Credentials failing, webhook silent, AI skipping conversations.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>

  <Card title="WhatsApp channel" icon="whatsapp" href="/whatsapp/introduction">
    OpenCX's native WhatsApp channel, if you don't route through Infobip.
  </Card>
</CardGroup>


# Infobip overview
Source: https://docs.open.cx/integrations/infobip/overview

Run Infobip Conversations as the surface your agents work in while OpenCX answers across WhatsApp, SMS, email, and live chat.

OpenCX works alongside your team inside Infobip Conversations. The AI replies on the same conversation your customer is writing to — whatever the channel — escalates cleanly when automation stops, and leaves an AI-written internal note on every handoff so your rep picks up with full context.

<Tip>
  Setup starts at [**Settings →
  Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX
  dashboard.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="One AI across every Infobip channel" icon="layer-group">
    WhatsApp, SMS, email, live chat, RCS, Viber, Messenger, Instagram, Telegram, and more — whatever channel the conversation arrives on, OpenCX receives it, matches it to a session, and the AI replies back on the same channel as the Infobip agent you designate.
  </Accordion>

  <Accordion title="Assignment decides what the AI touches" icon="route">
    The AI only answers conversations assigned to the dedicated **AI Agent** you
    pick in settings. Optionally enable **Handle unassigned conversations** to
    also let the AI claim conversations no one owns yet — it assigns them to
    itself before replying, so ownership is always explicit.
  </Accordion>

  <Accordion title="Handoff preserves the thread" icon="user-group">
    When the AI escalates, OpenCX posts an internal note with the AI summary and
    detected sentiment, tags the conversation `opencx_handed_off`, and unassigns
    it so your Infobip routing can pick it up. The customer never sees the note;
    your rep reads it before typing.
  </Accordion>

  <Accordion title="Status stays in sync both ways" icon="rotate">
    When the AI resolves, OpenCX tags the conversation `opencx_resolved` and (by
    default) closes it in Infobip with a resolution note. When a rep closes or
    reopens the conversation in Infobip, the matching OpenCX session closes or
    reopens too.
  </Accordion>

  <Accordion title="Infobip context lands on the session" icon="sliders">
    Conversation attributes (priority, channel, queue, topic) arrive on the OpenCX session as `ib_*` custom data, and the customer's Infobip People profile attributes land on the contact — so Autopilot actions and your reps see the same context Infobip has.
  </Accordion>
</AccordionGroup>

## How a message flows

```mermaid theme={"dark"}
flowchart LR
  A[Customer message on any Infobip channel] --> B[Infobip subscription webhook]
  B --> C[OpenCX matches conversation + contact]
  C --> D[AI replies as your AI Agent]
```

Contacts are matched by the customer's phone number or email from the inbound message. Media the customer sends (images, files, audio, video) is copied into OpenCX storage so it stays visible after Infobip's links expire.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Infobip" icon="plug" href="/integrations/infobip/connect">
    Create an API key, pick your AI agent, register the webhook subscription.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/infobip/troubleshooting">
    AI not replying, webhook silent, conversations not closing.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>

  <Card title="Autopilot topics" icon="robot" href="/handoff/topics">
    Control which topics the AI answers versus escalates.
  </Card>
</CardGroup>


# Infobip troubleshooting
Source: https://docs.open.cx/integrations/infobip/troubleshooting

Debug Infobip credentials, webhook subscriptions, assignment gating, media delivery, and conversation status sync.

Before debugging, have this ready:

* Your Infobip <Tooltip>Base URL</Tooltip> and the **AI Agent** selected in the integration settings.
* A specific OpenCX session ID (from [Inbox](https://platform.open.cx/inbox)) or Infobip conversation ID where the problem shows.

<Tip>
  Most issues are one of two things: the webhook subscription was never created
  in the Infobip portal, or the conversation isn't assigned to the AI agent.
  Check those first.
</Tip>

## Common scenarios

| Symptom | Likely cause | Where to check |
| - | - | - |
| AI never replies to anything | Webhook subscription missing in Infobip — registering it is a manual step | Infobip portal → subscriptions; compare receiver URL with the one in [OpenCX settings](https://platform.open.cx/settings/integrations) |
| AI replies to some conversations but not others | Conversation isn't assigned to the AI agent, and **Handle unassigned conversations** is off | Infobip Conversations dashboard — check the assignee |
| Connect fails with a credentials error | Wrong Base URL, or the API key lacks the **conversations:manage** scope | Infobip **Developer Tools → API Keys** — recreate the key with the right scope |
| Customer images/files missing from the session | Media re-hosting failed; OpenCX falls back to Infobip's short-lived link, which expires | Open the session soon after — if the link is dead, check the session timeline for upload errors and contact support |
| AI resolved, but the Infobip conversation stayed open | **Close Infobip conversation when resolved** is toggled off, or another agent owned the conversation at resolve time | [OpenCX Infobip settings](https://platform.open.cx/settings/integrations) + the conversation's assignee history |
| None of the above | Open a support request with the session ID, the Infobip conversation ID, and a timestamp | [support@open.cx](mailto:support@open.cx) |

### **AI went quiet after a human touched the conversation**

<Tooltip>
  Likely cause
</Tooltip>

: the conversation was assigned to a human or closed in Infobip.

**Fix:** this is expected — once a human owns the conversation, the AI stays out of it. Reassign the conversation to the AI agent in Infobip to resume AI handling.

### **Handoffs land unrouted in Infobip**

<Tooltip>
  Likely cause
</Tooltip>

: no Infobip routing picks up unassigned conversations.

**Fix:** point your Infobip routing at the `opencx_handed_off` tag, or have your team work the unassigned queue. The AI's summary and sentiment are in the internal note on the conversation.

### **WhatsApp replies fail after a day of silence**

<Tooltip>
  Likely cause
</Tooltip>

: the 24-hour WhatsApp window closed.

**Fix:** the customer's next inbound message reopens the window. To reach out first, send a pre-approved WhatsApp template from Infobip.

## Limits & timing

| | Value |
| - | - |
| **Duplicate webhook deliveries** | Repeated deliveries of the same message are ignored for 24 hours |
| **Inbound media** | Copied into OpenCX storage; if the copy fails, the original Infobip link is kept, but it is short-lived and will eventually expire |
| **AI replies** | Text only — the AI does not send images or files back through Infobip |
| **Closed conversations** | Infobip rejects writes to closed conversations; the AI cannot reply until the conversation is reopened |

***

## Related Documentation

<CardGroup>
  <Card title="Connect Infobip" icon="plug" href="/integrations/infobip/connect">
    Re-verify credentials, the AI agent, and the webhook subscription.
  </Card>

  <Card title="Overview" icon="comments" href="/integrations/infobip/overview">
    What the Infobip integration does and how messages flow.
  </Card>

  <Card title="Human handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>

  <Card title="Autopilot topics" icon="robot" href="/handoff/topics">
    Control which topics the AI answers versus escalates.
  </Card>
</CardGroup>


# Email
Source: https://docs.open.cx/integrations/intercom/channels/email

Route email conversations from Intercom through OpenCX AI with handoff to your Intercom inbox.

Email conversations that arrive in Intercom are handled the same way as Messenger chats — OpenCX picks them up via webhook, generates an AI reply, and posts it back as the AI admin. The key difference is a longer initial processing delay and email-specific formatting.

## Pre-requisites

<Warning>
  **Connect your Intercom workspace first.** The AI has nothing to respond to until the webhook is active — start with [Connect Intercom](/integrations/intercom/connect) and come back here.
</Warning>

* **Intercom connected and webhook active** — see [Connect Intercom](/integrations/intercom/connect).
* **Email channel configured in Intercom** — your Intercom workspace must be receiving emails (via forwarding or a connected inbox).

## How conversations land in Intercom

```mermaid theme={"dark"}
flowchart LR
  A[Customer emails your support address] --> B[Email arrives in Intercom]
  B --> C[AI replies via Intercom email]
  C --> D{AI can resolve?}
  D -- Yes --> E[Conversation resolved]
  D -- No --> F[Handoff note + unassign]
  F --> G[Rep picks up in Intercom inbox]
  G --> H[Rep replies — lands in customer's inbox]
```

## Setting up

<Steps>
  <Step title="Confirm email is routing to Intercom">
    Send a test email to the address Intercom is configured to receive. The conversation should appear in your Intercom inbox.
  </Step>

  <Step title="Confirm the AI processes the email">
    The AI should reply within approximately 30 seconds (email conversations have a longer initial delay). Check that the reply appears as a message from the AI admin.
  </Step>

  <Step title="Trigger a test handoff">
    Reply to the email thread with something like *"I want to talk to a human."* The AI should hand off — you'll see an internal handoff note and the conversation moved to your team's queue.
  </Step>

  <Step title="Verify the rep reply loop">
    Pick up the handed-off conversation in your Intercom inbox. Reply as an agent — the message should land in the customer's email inbox.
  </Step>
</Steps>

<Tip>
  If the AI doesn't reply to emails, confirm that the conversation is being assigned to the AI admin. Some Intercom routing rules may assign email conversations to a human team by default.
</Tip>

## What the rep sees

* The conversation appears in their **Intercom inbox** as an email thread.
* The full AI-to-customer transcript is already in the thread.
* An **internal handoff note** with summary, sentiment, and language.
* `opencx_handed_off` tag on the conversation for filtering views and reports.
* Replies sent from the Intercom inbox land in the customer's email inbox.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Longer initial processing delay" icon="clock">
    OpenCX waits approximately **30 seconds** after the first email message before processing — significantly longer than the 4-second wait for Messenger. This gives Intercom time to finalize the conversation, apply routing rules, and assign the conversation to the AI admin. Email delivery is asynchronous, so this delay does not affect the customer's experience.
  </Accordion>

  <Accordion title="Outbound email automations are ignored" icon="filter">
    Emails initiated by Intercom outbound campaigns, automated sequences, or templates (where the source is not `customer_initiated`) are skipped. This prevents the AI from responding to your own email marketing.
  </Accordion>

  <Accordion title="Attachment handling" icon="paperclip">
    Email attachments follow the same rules as Messenger: supported image types are downloaded and uploaded to OpenCX storage. PDFs, videos, and audio files are forwarded as placeholder text when **Forward unsupported attachments** is enabled in [settings](/integrations/intercom/connect#settings-reference). Otherwise they are acknowledged but not processed.
  </Accordion>

  <Accordion title="Email thread formatting" icon="list">
    Intercom handles email threading natively. When the AI replies, the response appears as a new message in the email thread. Quoted previous messages and signatures are managed by Intercom's email formatting — OpenCX processes the latest message content only.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Web (Messenger)" icon="comments" href="/integrations/intercom/channels/web">
    Messenger conversation specifics on top of the shared setup.
  </Card>

  <Card title="Connect Intercom" icon="plug" href="/integrations/intercom/connect">
    Credentials, webhook, and admin selection.
  </Card>

  <Card title="Intercom overview" icon="intercom" href="/integrations/intercom/overview">
    What else the Intercom integration covers.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/intercom/troubleshooting">
    AI not replying to emails, webhook errors, handoff not firing.
  </Card>
</CardGroup>


# Web (Messenger)
Source: https://docs.open.cx/integrations/intercom/channels/web

Route Intercom Messenger conversations through OpenCX AI with handoff to your Intercom inbox.

Messenger conversations are the primary channel for the Intercom integration. When a customer opens Intercom's <Tooltip>Messenger</Tooltip> and sends a message, OpenCX picks it up via webhook, generates an AI reply, and posts it back as the AI admin. If the AI can't resolve, it hands off to your team in the same Intercom thread.

## Pre-requisites

<Warning>
  **Connect your Intercom workspace first.** The AI has nothing to respond to until the webhook is active — start with [Connect Intercom](/integrations/intercom/connect) and come back here.
</Warning>

* **Intercom connected and webhook active** — see [Connect Intercom](/integrations/intercom/connect).
* **Default AI admin selected** — see [Connect → Select the default admin](/integrations/intercom/connect#setup).

## How conversations land in Intercom

```mermaid theme={"dark"}
flowchart LR
  A[Visitor opens Messenger] --> B[AI replies in Messenger]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation resolved]
  C -- No --> E[Handoff note + unassign]
  E --> F[Rep picks up in Intercom inbox]
  F --> G[Rep replies — lands in Messenger]
```

## Setting up

<Steps>
  <Step title="Confirm the Messenger is live">
    Open a page where Intercom's Messenger is installed and send a test message. You should see the AI respond within a few seconds.
  </Step>

  <Step title="Confirm the webhook is receiving events">
    In your Intercom Developer Hub, check the webhook activity log. Recent deliveries should show `2xx` responses. If you see failures, re-copy the webhook URL from [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Step>

  <Step title="Trigger a test handoff">
    Send a message like *"I want to talk to a human"* in the Messenger. The AI should hand off the conversation — you'll see an internal handoff note and the conversation moved to your team's queue.
  </Step>

  <Step title="Verify the rep reply loop">
    Pick up the handed-off conversation in your Intercom inbox. Reply as an agent — the message should land in the visitor's Messenger within a couple of seconds.
  </Step>
</Steps>

<Tip>
  If the AI doesn't reply, check that the conversation is assigned to the AI admin and that [Autopilot](https://platform.open.cx/settings/autopilot) is enabled for the web channel.
</Tip>

## What the rep sees

* The conversation appears in their **Intercom inbox** like any other Messenger chat.
* The full AI-to-visitor transcript is already in the thread — no separate tool to check.
* An **internal handoff note** with summary, sentiment, and language.
* `opencx_handed_off` tag on the conversation for filtering views and reports.
* Replies typed in the Intercom inbox land back in the visitor's Messenger within a couple of seconds.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Initial processing delay" icon="clock">
    OpenCX waits approximately **4 seconds** after the first message before processing. This gives Intercom time to finalize the conversation assignment and apply any automation rules. Subsequent messages in the same conversation are processed immediately.
  </Accordion>

  <Accordion title="Inline images from Messenger" icon="image">
    Images customers send in Messenger are extracted from the HTML body, downloaded from Intercom's CDN, and uploaded to OpenCX storage. The AI can reference them in its reasoning. If an image download fails, a placeholder attachment is added instead.
  </Accordion>

  <Accordion title="Custom attribute delay" icon="hourglass">
    If your Intercom workflows set custom attributes on conversations after creation (e.g. via bots or rules), configure the **custom attribute delay** in [settings](/integrations/intercom/connect#settings-reference). OpenCX re-fetches attributes after the configured delay to capture values set by your automations. Max 10 seconds.
  </Accordion>

  <Accordion title="Outbound automations are ignored" icon="filter">
    Conversations initiated by Intercom outbound messages, templates, or bots (where the source is not `customer_initiated`) are skipped. This prevents the AI from responding to your own marketing automations.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Email channel" icon="envelope" href="/integrations/intercom/channels/email">
    Email conversation specifics on top of the shared setup.
  </Card>

  <Card title="Connect Intercom" icon="plug" href="/integrations/intercom/connect">
    Credentials, webhook, and admin selection.
  </Card>

  <Card title="Intercom overview" icon="intercom" href="/integrations/intercom/overview">
    What else the Intercom integration covers.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/intercom/troubleshooting">
    AI not replying, webhook errors, handoff not firing.
  </Card>
</CardGroup>


# Connect Intercom
Source: https://docs.open.cx/integrations/intercom/connect

Generate an access token, copy your workspace and teammate IDs, enter credentials, configure the webhook, and choose how handoffs are routed.

One-time setup: enter your Intercom credentials, pick the teammate the AI replies as, paste the webhook URL into Intercom, and choose how handoffs are routed.

<IntercomFlow />

<Info>
  This page covers the shared Intercom connection. Once connected, see the [Web](/integrations/intercom/channels/web) or [Email](/integrations/intercom/channels/email) channel pages for per-channel verification steps.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Intercom workspace with API access" icon="key">
    You need an Intercom workspace on a plan that includes API access. You also need admin-level permissions to generate access tokens in the Developer Hub.
  </Accordion>

  <Accordion title="Admin access in OpenCX" icon="shield-check">
    Only organization admins can connect integrations. Confirm your role at [**Settings → Organization**](https://platform.open.cx/settings).
  </Accordion>

  <Accordion title="A dedicated Intercom teammate for the AI" icon="user-plus">
    Designate or create a teammate that represents the AI (for example, "AI Assistant"). Customers see this teammate as the author of every AI reply, so a dedicated bot account is strongly preferred over a real teammate's account. You'll copy this teammate's ID in step 3.
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Generate an access token">
    In Intercom, go to **Settings → Integrations → Developer Hub**. Create a new app if you don't already have one, or open an existing app.

    Inside the app, open **Authentication** and copy the **Access token** displayed beneath the app name. You can return to this page at any time to view the token again.

    <Warning>
      Treat this access token like a password. It grants full read and write access to your Intercom conversations and contacts — don't share it, don't paste it into shared channels or tickets, and rotate it immediately if you suspect it has leaked.
    </Warning>
  </Step>

  <Step title="Copy your workspace ID">
    In Intercom, go to **Settings → Workspace → General** and copy the **App ID** field. Intercom uses "App ID" and "Workspace ID" interchangeably — they refer to the same value.
  </Step>

  <Step title="Copy your AI teammate ID">
    Use the dedicated teammate from the prerequisites (create one first if you haven't).

    In Intercom, go to **Settings → Workspace → Teammates** and click the teammate. The teammate ID appears as the last segment of the URL on the profile page:

    ```
    app.intercom.com/a/apps/<WORKSPACE_ID>/admins/<TEAMMATE_ID>
    ```

    Copy `<TEAMMATE_ID>` — that's the value you'll paste into the **AI Admin ID** field in OpenCX.

    <Warning>
      Every AI-generated reply is posted as this teammate. Use a dedicated bot account (for example, "AI Assistant") rather than a real teammate to avoid confusion with your team's own replies.
    </Warning>
  </Step>

  <Step title="Enter credentials in OpenCX">
    Open [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard and select **Intercom**. OpenCX generates a webhook URL the moment the modal opens — you'll use it in the next step.

    Fill in:

    | Field | Value |
    | - | - |
    | **Access token** | The token from step 1. |
    | **Workspace ID** | The App ID from step 2. |
    | **AI Admin ID** | The teammate ID from step 3. |

    Click **Save**. OpenCX validates the credentials by listing your Intercom conversations. If validation fails, double-check that the token has not been revoked and that your Intercom plan includes API access.
  </Step>

  <Step title="Configure the webhook">
    Still in the OpenCX modal, copy the **Webhook URL**.

    In Intercom, go to **Settings → Integrations → Developer Hub → choose your app → Webhooks** and paste the URL. See Intercom's [webhook setup guide](https://developers.intercom.com/docs/webhooks/setting-up-webhooks) for reference.

    Subscribe to these topics:

    * `conversation.user.created`
    * `conversation.user.replied`
    * `conversation.admin.replied`
    * `conversation.admin.noted`
    * `conversation.admin.assigned`
    * `conversation.admin.open.assigned`
    * `conversation.admin.closed`
    * `conversation.admin.opened`
    * `conversation.admin.snoozed`
    * `conversation.admin.unsnoozed`
    * `conversation.priority.updated`

    <Warning>
      Without the webhook, OpenCX cannot receive conversation events and the AI will not respond to any messages. If you later change the app or rotate the token, re-verify that the webhook is still pointing at the OpenCX URL.
    </Warning>
  </Step>

  <Step title="Configure handoff assignment">
    Choose what happens when the AI hands off a conversation:

    * **Unassigned** (default) — removes the AI teammate and leaves the conversation in your triage queue for any teammate to pick up.
    * **Specific teammate** — assigns to a named teammate on handoff.
    * **Specific team** — assigns to an Intercom team on handoff.
    * **Team and teammate** — assigns to both a team and a specific teammate simultaneously.
  </Step>

  <Step title="Enable full conversation sync (optional)">
    Open the **Sync Settings** tab inside the Intercom modal and toggle **Full Conversation Auto Sync** to sync every conversation in your Intercom workspace — not only the ones assigned to the AI teammate.

    <Info>
      Non-AI conversations are stored for reporting, insights, and supervision, and are **not billed** as AI interactions. With this on, the AI can also be brought into a conversation partway through by assigning it to the AI teammate.
    </Info>
  </Step>

  <Step title="Send a test message">
    Open your Intercom Messenger and send a test message. The AI should reply within a few seconds. Then say *"I want to talk to a human"* — you should see an internal handoff note appear, and the conversation should be unassigned (or reassigned per your handoff configuration).

    <Info>
      For channel-specific verification, see [Web](/integrations/intercom/channels/web#setting-up) or [Email](/integrations/intercom/channels/email#setting-up).
    </Info>
  </Step>
</Steps>

## Settings reference

All settings are configured at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) → Intercom, across the **Connection**, **Handoff Settings**, and **Sync Settings** tabs.

| Setting | Purpose |
| - | - |
| **Default teammate** (AI Admin ID) | The Intercom teammate the AI replies as. Required. |
| **Default team** | Fallback team for routing. Optional. |
| **Handoff assignment** | Where conversations go on handoff: unassigned, specific teammate, specific team, or both team and teammate. |
| **Ignore first message** | Skip AI processing on the opening message. Useful when Intercom bots handle the greeting. |
| **Process on assignment** | Wait for the conversation to be assigned to the AI teammate before processing, instead of processing on the first message. |
| **Full conversation sync** | Configured in the **Sync Settings** tab. Stores every Intercom conversation in OpenCX — not just those assigned to the AI — for reporting and supervision. |
| **Forward unsupported attachments** | Pass PDF, video, and audio attachments to the AI as placeholder text so it can acknowledge them. |
| **Send citations as note** | Post an internal note linking to the AI's source citations in OpenCX after each reply. |
| **Company data sync** | Sync custom attributes from the contact's Intercom company to their OpenCX profile. Options: disabled, first company only, all companies. |
| **Custom attribute delay** | Seconds to wait before re-fetching conversation custom attributes after creation. Handles Intercom race conditions where attributes are set by workflows after the conversation is created. Max 10 seconds. |

## Link human teammates

After connecting Intercom, open **Settings → Linked Accounts** and find the **Intercom** section. Click **Sync**, then review the automatic email matches or select each member's Intercom account. Each Intercom teammate can be linked to only one OpenCX member in the workspace. Only teammates with an Inbox seat can be linked; Fin is not a human account mapping.

Changing mappings requires permission to manage integrations. Members who can view integrations or manage members can view the mappings. The mapping controls who authors an inbox reply, internal note, or manual status change in Intercom. An unlinked sender uses the configured default teammate.

## Map snooze to an OpenCX status

In **Settings → Integrations → Intercom → Sync Settings → Snooze**, select an open session status under **Snoozed status** and set **Snooze duration (hours)**. The default duration is 24 hours. Save the settings.

Applying that status in OpenCX snoozes the linked Intercom session. Clearing it opens the Intercom session again. Intercom snooze and unsnooze events update that status in OpenCX; a customer reply that opens the Intercom session also clears it. Other OpenCX statuses are preserved when an unsnooze arrives. Select no mapped status to disable snooze synchronization.

When Intercom is your ticketing system, a new customer reply received directly in OpenCX also returns an open, linked session with the mapped snooze status to native **Open**, with no custom status, and clears snooze in Intercom. Other custom statuses, the assigned teammate, and human handoff remain unchanged. Duplicate replies and replies that predate a newer recorded snooze do not clear it.

## Disconnecting

To remove the Intercom integration, open [**Settings → Integrations**](https://platform.open.cx/settings/integrations) → Intercom and click **Disconnect**. This deletes stored credentials and stops webhook processing. Existing OpenCX sessions are preserved but no longer receive updates from Intercom.

***

## Related Documentation

<CardGroup>
  <Card title="Conversations" icon="messages" href="/integrations/intercom/conversations">
    How messages flow, handoff steps, and tags.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/intercom/channels/web">
    Per-channel implementation details for Web and Email.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/intercom/troubleshooting">
    Credentials failing, webhook silent, AI not replying.
  </Card>
</CardGroup>


# Conversations
Source: https://docs.open.cx/integrations/intercom/conversations

How OpenCX processes Intercom conversations, hands off to your team, syncs tags, and tracks resolution.

Once your Intercom workspace is [connected](/integrations/intercom/connect), OpenCX listens for conversation events via webhook and processes them in real time. This page covers the shared flow that applies to every channel — see [Web](/integrations/intercom/channels/web) and [Email](/integrations/intercom/channels/email) for per-channel specifics.

## How conversations flow

```mermaid theme={"dark"}
flowchart LR
  A[Customer messages] --> B[Intercom webhook]
  B --> C[OpenCX AI]
  C --> D{Can resolve?}
  D -- Yes --> E[AI replies in Intercom]
  D -- No --> F[Handoff note + unassign]
  F --> G[Rep picks up in Intercom]
```

## What the AI listens for

OpenCX handles these Intercom webhook events:

| Event | What OpenCX does |
| - | - |
| **New customer message** | Creates a session and generates an AI reply. Skips outbound automations and bot-initiated conversations. |
| **Customer reply** | Continues AI processing on the existing session. |
| **Admin reply** | Stores the reply in the conversation history for context. Does not trigger AI processing. |
| **Assignment change** | If the conversation is assigned to the AI admin and **Process on assignment** is enabled, the AI picks up and processes the full thread. |
| **Conversation closed** | Resolves the linked OpenCX session. A close while assigned to the AI admin also records an assumed AI resolution. |
| **Conversation opened** | Reopens the linked OpenCX session. |
| **Snoozed or unsnoozed** | Applies or clears the configured snooze status. |
| **Priority changed** | Updates `Intercom Priority` in the session's custom data. |

<Note>
  Intercom classifies conversations as either **web** (Messenger) or **email** based on how the customer initiated contact. OpenCX maps these to its own channel types automatically.
</Note>

## Handoff to your team

When the AI decides it cannot resolve a conversation, it hands off in four steps:

<Steps>
  <Step title="Post an internal note">
    OpenCX posts an internal note to the Intercom conversation containing a summary of what the customer asked, the detected sentiment, and the conversation language. Your rep sees this immediately when they open the conversation.
  </Step>

  <Step title="Tag the conversation">
    The conversation is tagged `opencx_handed_off` so you can filter handoffs in your Intercom views and reports.
  </Step>

  <Step title="Unassign or reassign">
    Based on your [handoff assignment setting](/integrations/intercom/connect#settings-reference):

    * **Unassigned**: the AI admin is removed and the conversation enters your team's unassigned queue.
    * **Specific admin**: the conversation is assigned to the admin you configured.
    * **Specific team**: the conversation is assigned to the team you configured.
  </Step>

  <Step title="Session stays open">
    The OpenCX session remains open so the human rep's replies are tracked. The conversation history stays intact for reporting and audit.
  </Step>
</Steps>

## Work from the OpenCX inbox

Link your [human teammates](/integrations/intercom/connect#link-human-teammates) to author inbox replies and internal notes as their Intercom accounts. An unlinked sender uses the configured default teammate. Incoming teammate replies retain the linked sender's identity in OpenCX.

Files attached in OpenCX are sent with their filenames and file types. Intercom determines whether each file appears as an inline preview or a download. If Intercom rejects an attachment, OpenCX can send the text without that file; check the delivery result before retrying. When delivery cannot be confirmed, OpenCX reports the uncertainty to avoid sending the same message twice.

Manually setting a session to **Resolved** or **Unresolved** closes its Intercom session. Reopening it opens the Intercom session again. These actions use the acting member's linked account, or the configured default teammate. Configure [snooze mapping](/integrations/intercom/connect#map-snooze-to-an-opencx-status) separately.

Intercom priority appears as **Intercom Priority** in session custom data. This field is imported from Intercom; editing it in OpenCX does not update Intercom priority. Incoming changes depend on the matching Intercom webhook reaching OpenCX, so delivery delays can affect when they appear.

## Tags OpenCX applies

| Tag | When it appears |
| - | - |
| `opencx_handed_off` | AI decided to escalate the conversation. |
| `opencx_ai_assisted` | Assist Mode posted a draft as an internal note. Assist is a [discouraged fallback](/integrations/intercom/troubleshooting#assist-mode-not-posting-suggestions) — prefer autopilot. |
| Session-level tags | Any tags you define on the OpenCX session sync to the Intercom conversation automatically. |

## Full conversation sync

When **Full conversation sync** is enabled in [settings](/integrations/intercom/connect#settings-reference), OpenCX stores all conversation messages — even from conversations the AI never touched. No AI processing runs; messages are recorded as-is for reporting, analytics, and supervision.

<AccordionGroup>
  <Accordion title="When to enable full sync" icon="arrows-rotate">
    Enable this when you want OpenCX to be the single source of truth for all customer conversations. Useful for teams that use OpenCX reporting and insights but don't want the AI actively participating in every conversation.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Intercom" icon="plug" href="/integrations/intercom/connect">
    Credentials, webhook, admin selection, and settings.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/intercom/channels/web">
    Per-channel details for Web and Email.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/intercom/troubleshooting">
    Handoff not firing, AI not replying, duplicate messages.
  </Card>
</CardGroup>


# Intercom overview
Source: https://docs.open.cx/integrations/intercom/overview

Run Intercom as the inbox your agents work in while OpenCX resolves, routes, and hands off conversations with full context.

OpenCX works alongside your agents inside Intercom. The AI resolves what it can, escalates what it can't, and posts a handoff note with summary, sentiment, and language straight into the conversation your reps already live in — no separate inbox, no context rebuild.

<Tip>
  Setup starts at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="Conversations your reps pick up with full context" icon="message">
    When the AI escalates, OpenCX posts an internal note with a conversation summary, detected sentiment, and language. The customer's full transcript is already in the Intercom thread — your rep reads one conversation, not two tools.
  </Accordion>

  <Accordion title="Configurable handoff routing" icon="route">
    Choose what happens when the AI hands off: leave the conversation unassigned, route it to a specific admin, or route it to a specific team. Each option maps to how your Intercom inbox already distributes work.
  </Accordion>

  <Accordion title="Company and contact data that follows the conversation" icon="building">
    OpenCX syncs custom attributes from your Intercom contacts and their attached companies into the AI's context. The AI sees the same data your reps see — plan tier, account manager, contract date — without manual lookup.
  </Accordion>

  <Accordion title="Every conversation traced back to your AI" icon="tag">
    OpenCX tags every conversation it touches with `opencx_handed_off` on escalation, and optionally posts a citation note linking back to the OpenCX session. Your reps audit AI reasoning in one click.
  </Accordion>
</AccordionGroup>

## Supported channels

Pick the channel you want to wire through Intercom — each page covers the specifics for that channel on top of the shared setup.

<CardGroup>
  <Card title="Web (Messenger)" icon="comments" href="/integrations/intercom/channels/web">
    Live Messenger conversations handed off to your Intercom inbox.
  </Card>

  <Card title="Email" icon="envelope" href="/integrations/intercom/channels/email">
    Email conversations handed off to your Intercom inbox.
  </Card>
</CardGroup>

## Observability

Every conversation OpenCX touches in Intercom is traceable back to the exact OpenCX session. Your reps debug in the tool they already use; your admins audit without re-running the AI.

<AccordionGroup>
  <Accordion title="Tags on every conversation" icon="tag">
    OpenCX applies `opencx_handed_off` when the AI escalates. Session-level tags you define in OpenCX sync to the Intercom conversation automatically. Filter your Intercom views and reports on these without leaving Intercom.
  </Accordion>

  <Accordion title="Handoff notes with AI reasoning" icon="note-sticky">
    Every handoff posts an internal note containing the conversation summary, detected sentiment, and language. Your rep opens the conversation and immediately knows **why** the AI escalated and **what** the customer needs.
  </Accordion>

  <Accordion title="Citation links back to OpenCX" icon="link">
    When **Send citations as note** is enabled, OpenCX posts an internal note linking to the session in your [Inbox](https://platform.open.cx/inbox). One click opens the full transcript, tool calls, AI reasoning, and handoff event.
  </Accordion>
</AccordionGroup>

## Get started

Connect your Intercom workspace, select the admin the AI replies as, and paste the webhook URL into Intercom.

<Card title="Connect Intercom" icon="plug" href="/integrations/intercom/connect">
  Credentials, webhook setup, and handoff configuration.
</Card>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Intercom" icon="plug" href="/integrations/intercom/connect">
    Credentials, webhook, admin selection, and settings.
  </Card>

  <Card title="Knowledge Sync" icon="book" href="/knowledge/sources/intercom/connect">
    Train the AI on your Intercom conversation data.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/intercom/troubleshooting">
    Credentials failing, webhook silent, AI not replying.
  </Card>
</CardGroup>


# Intercom troubleshooting
Source: https://docs.open.cx/integrations/intercom/troubleshooting

Debug Intercom connection, webhook, handoff, Assist Mode, and sync issues — 401 credential failures, duplicate messages, silent AI, missing handoffs.

Before debugging, have this ready:

* Your Intercom <Tooltip>access token</Tooltip> and <Tooltip>workspace ID</Tooltip>.
* A specific <Tooltip>session ID</Tooltip> (from [Inbox](https://platform.open.cx/inbox)) or Intercom conversation ID where the problem shows.
* The webhook URL shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Intercom.

<Tip>
  Re-run **Verify** in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Intercom as your first step. Most issues are credential or webhook related.
</Tip>

<Info>
  **Fastest path to root cause:** find the conversation in your [OpenCX Inbox](https://platform.open.cx/inbox) and check the session's AI reasoning, tool calls, and handoff event. That's far faster than inspecting webhooks or logs.
</Info>

## Common scenarios

Jump to the symptom that matches what you're seeing.

### **"Failed to verify credentials" on save**

<Tooltip>Likely cause</Tooltip>: token revoked, workspace ID wrong, or plan doesn't include API access.

**Fix:** regenerate the access token in Intercom's [Developer Hub](https://developers.intercom.com/). Confirm the workspace ID matches your Intercom URL. Confirm your Intercom plan includes API access.

### **Webhook not receiving events**

<Tooltip>Likely cause</Tooltip>: webhook URL not configured in Intercom, or wrong event subscriptions.

**Fix:** open your Intercom app in the Developer Hub and confirm the webhook URL matches the one shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Intercom. Confirm you're subscribed to all five required topics: `conversation.user.created`, `conversation.user.replied`, `conversation.admin.replied`, `conversation.admin.assigned`, `conversation.admin.closed`.

### **AI not responding to conversations**

<Tooltip>Likely cause</Tooltip>: conversation not assigned to AI admin, Autopilot disabled, or **Process on assignment** is enabled but the conversation hasn't been assigned yet.

**Fix:** check these in order:

1. Confirm the conversation is assigned to the admin you selected as the default AI admin in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Intercom.
2. Confirm [Autopilot](https://platform.open.cx/settings/autopilot) is enabled for the channel (web or email).
3. If **Process on assignment** is enabled, the AI waits for an explicit assignment event — check that your Intercom routing rules assign new conversations to the AI admin.
4. Confirm the conversation was customer-initiated (outbound automations and bot messages are skipped).

### **Handoff creates a note but conversation stays assigned to AI**

<Tooltip>Likely cause</Tooltip>: concurrent webhook events re-assigned the conversation before the handoff completed.

**Fix:** this is a transient timing issue. OpenCX uses a lock to prevent race conditions, but rapid concurrent events can occasionally conflict. If this happens consistently, open a support request with the session ID.

### **Duplicate AI replies on the same message**

<Tooltip>Likely cause</Tooltip>: dedup window expired or concurrent webhook retries.

**Fix:** OpenCX deduplicates messages by content hash with a 1-hour window. If Intercom retries a webhook delivery after the window expires, a duplicate can occur. This is rare — if it happens consistently, confirm your Intercom webhook is not configured to retry aggressively.

### **Assist Mode not posting suggestions**

<Warning>
  **Assist Mode is a discouraged fallback.** We recommend [autopilot](/handoff/introduction) for every new deployment — Assist exists only for teams that aren't yet ready to hand customer replies to the AI. If you're evaluating OpenCX, start with autopilot.
</Warning>

If you're already running Assist, <Tooltip>likely cause</Tooltip>: conversation is assigned to the AI admin (Assist only runs on human-owned conversations), or Autopilot assist is disabled.

**Fix:** check these in order:

1. Confirm the conversation is assigned to a human agent, **not** the AI admin.
2. Confirm [Autopilot](https://platform.open.cx/settings/autopilot) assist is enabled for the channel.
3. Check if the topic is on the no-assist list in Autopilot settings.
4. The AI may have judged its own suggestion unhelpful and stayed quiet — check the session in [Inbox](https://platform.open.cx/inbox) for reasoning.

<AccordionGroup>
  <Accordion title="How to enable Assist (if you must)" icon="gear">
    Assist runs on the same webhook as direct AI replies — no extra credentials.

    1. Complete the [Intercom connection](/integrations/intercom/connect).
    2. In [Autopilot](https://platform.open.cx/settings/autopilot), enable assist per-channel (web or email).
    3. Assist only fires on conversations **not** assigned to the AI admin.

    Conversations Assist writes to are tagged `opencx_ai_assisted`. Drafts post as internal notes — the customer never sees them.
  </Accordion>
</AccordionGroup>

### **Custom attributes not appearing on session**

<Tooltip>Likely cause</Tooltip>: attribute not API-writable, or delay too short.

**Fix:** in Intercom, confirm the custom attribute is marked as API-writable. If your Intercom workflows set attributes after conversation creation, increase the **custom attribute delay** in [settings](/integrations/intercom/connect#settings-reference) (max 10 seconds).

### **Company data not syncing to contact**

<Tooltip>Likely cause</Tooltip>: sync disabled or contact has no company.

**Fix:** confirm **Company data sync** is set to "first company" or "all companies" in [settings](/integrations/intercom/connect#settings-reference). Confirm the Intercom contact has at least one company attached.

## Limits & timing

| | Value |
| - | - |
| **Initial webhook wait (web)** | \~4 seconds |
| **Initial webhook wait (email)** | \~30 seconds |
| **Message deduplication window** | 1 hour |
| **Session creation lock timeout** | 3 seconds |
| **Conversation unassign lock** | 500 ms |
| **Custom attribute delay** | 0–10 seconds (configurable) |
| **Resolution note delay** | \~15 seconds |

<Note>
  OpenCX retries on transient Intercom API failures but does not indefinitely retry. If your Intercom workspace is rate-limited or experiencing downtime, some webhook events may be missed. Check your Intercom Developer Hub webhook activity log for failed deliveries.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Intercom" icon="plug" href="/integrations/intercom/connect">
    Re-verify credentials and webhook setup.
  </Card>

  <Card title="Conversations" icon="messages" href="/integrations/intercom/conversations">
    How messages flow and how handoff works.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/intercom/channels/web">
    Per-channel details for Web and Email.
  </Card>

  <Card title="Handoff settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Connect Jira
Source: https://docs.open.cx/integrations/jira/connect

Generate an Atlassian API token, enter your credentials in OpenCX, and verify the connection to start creating Jira issues.

<Warning>
  The Jira integration is in **closed beta**. The setup steps below apply once your organization is enrolled. Contact [support@open.cx](mailto:support@open.cx) for access.
</Warning>

The Jira integration uses an <Tooltip>Atlassian API token</Tooltip> to authenticate with your Jira Cloud instance. OpenCX verifies the credentials before saving — a wrong domain or token returns an error and nothing persists.

<JiraFlow />

<Info>
  Setup takes about 5 minutes. You need admin access in both your Atlassian account and your OpenCX organization.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Jira Cloud account" icon="cloud">
    The integration works with **Jira Cloud only** (the `*.atlassian.net` hosted version). Jira Server and Jira Data Center are not supported.
  </Accordion>

  <Accordion title="Atlassian API token" icon="key">
    You generate this from your [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens). The token is bound to your Atlassian account — if the account is deactivated or loses project access, the integration stops working.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="user-shield">
    Required to save integration settings in [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Generate an Atlassian API token">
    Open [**Atlassian account → Security → API tokens**](https://id.atlassian.com/manage-profile/security/api-tokens) and click **Create API token**.

    1. Label it `OpenCX` (or anything recognizable).
    2. **Copy the token immediately** — Atlassian hides it after you close the dialog.

    <Warning>
      The token inherits the permissions of the Atlassian account that created it. Use an account with access to all Jira projects you want OpenCX to create issues in.
    </Warning>
  </Step>

  <Step title="Open Jira settings in OpenCX">
    In your OpenCX dashboard, go to [**Settings → Integrations**](https://platform.open.cx/settings/integrations) and select **Jira**.
  </Step>

  <Step title="Enter your credentials">
    | Field | Value |
    | - | - |
    | **Domain** | Your Atlassian Cloud domain — e.g. `acme.atlassian.net`. Include the full domain. |
    | **Email** | The email address of the Atlassian account that owns the API token. |
    | **API Token** | The token you just copied. |

    Click **Verify & Save**. OpenCX tests the connection by authenticating against your Jira instance before persisting. A wrong domain, expired token, or incorrect email returns an error.
  </Step>

  <Step title="Select a default project and issue type">
    After verification succeeds, select:

    * **Default project** — the Jira project where issues are created when no override is specified.
    * **Default issue type** — the issue type used by default (e.g. Task, Bug, Story).

    You can override both per issue when pushing recommendations or insights to Jira.
  </Step>

  <Step title="Verify end to end">
    Navigate to [**AI Recommendations**](https://platform.open.cx/reports/voice-of-customer) in your OpenCX dashboard. Pick any recommendation and push it to Jira. Within a few seconds:

    1. A new issue appears in your default Jira project.
    2. The issue description includes the recommendation summary and a link back to the OpenCX session.

    If the issue doesn't appear, check [Troubleshooting](/integrations/jira/troubleshooting).
  </Step>
</Steps>

## Configure field mappings

Map OpenCX data to your Jira custom fields so issues are populated with structured data on creation.

<Steps>
  <Step title="Open field mappings">
    In the Jira integration settings, navigate to the **Field Mappings** section.
  </Step>

  <Step title="Add a mapping">
    For each custom field you want to populate:

    | Setting | Description |
    | - | - |
    | **Jira field** | The Jira field to populate — select from your available fields. |
    | **OpenCX field** | The OpenCX data source to map from. |
    | **Custom field** | Toggle on if this is a Jira custom field (not a built-in field). |

    Mappings apply to all issues OpenCX creates. Built-in fields like project, issue type, and priority are configured in the main integration settings.
  </Step>
</Steps>

<Tip>
  Start with the fields your team filters and reports on most. You can add more mappings at any time without disrupting existing issues.
</Tip>

## Rotating the API token

Regenerating the Atlassian API token requires updating OpenCX:

1. Create a new token in [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens).
2. Paste it into [Settings → Integrations → Jira](https://platform.open.cx/settings/integrations) and save.
3. Revoke the old token in Atlassian.

## Disconnecting

In your OpenCX dashboard, open the Jira integration settings and click **Disconnect**. Issues already created in Jira remain untouched — disconnecting only stops future issue creation.

***

## Related Documentation

<CardGroup>
  <Card title="Overview" icon="list-check" href="/integrations/jira/overview">
    What the Jira integration does and how conversations become issues.
  </Card>

  <Card title="Issue Flow" icon="diagram-project" href="/integrations/jira/issue-flow">
    How issues are created from recommendations, insights, and conversations.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/jira/troubleshooting">
    Credentials failing, issues not created, field mappings missing.
  </Card>

  <Card title="Handoff" icon="user-group" href="/handoff/introduction">
    How conversations escalate to human agents and downstream integrations.
  </Card>
</CardGroup>


# Issue Flow
Source: https://docs.open.cx/integrations/jira/issue-flow

How OpenCX creates and populates Jira issues from AI Recommendations, Customer Insights, and live conversations.

<Warning>
  The Jira integration is in **closed beta**. The workflows below apply once your organization is enrolled. Contact [support@open.cx](mailto:support@open.cx) for access.
</Warning>

Once the Jira integration is [connected](/integrations/jira/connect), OpenCX creates issues from three sources: AI Recommendations, Customer Insights, and live conversations. Each path produces a structured Jira issue with conversation context, AI-generated summaries, and a link back to the originating session.

## How issues reach Jira

```mermaid theme={"dark"}
flowchart LR
  A[Conversations] --> B[AI analyzes patterns]
  B --> C[Recommendation]
  B --> D[Customer Insight]
  A --> E[Live detection]
  C --> F[Push to Jira]
  D --> F
  E --> F
  F --> G[Issue in your project]
```

## From AI Recommendations

<Tooltip href="https://platform.open.cx/reports/voice-of-customer">AI Recommendations</Tooltip> surface patterns the AI detects across your conversations — knowledge gaps, recurring complaints, product friction. When a recommendation is worth acting on, push it to Jira.

<Steps>
  <Step title="Open AI Recommendations">
    Navigate to [**AI Recommendations**](https://platform.open.cx/reports/voice-of-customer) in your OpenCX dashboard.
  </Step>

  <Step title="Review and push">
    Select a recommendation. Click **Push to Jira**. OpenCX uses the AI to generate:

    * **Summary** — a concise issue title derived from the recommendation.
    * **Description** — the recommendation detail with conversation evidence and a link back to the OpenCX session.
  </Step>

  <Step title="Override defaults (optional)">
    Before confirming, you can change the target project and issue type. If you don't, OpenCX uses the defaults you set during [setup](/integrations/jira/connect).
  </Step>
</Steps>

The created issue appears in your Jira project within seconds. OpenCX stores the issue key and URL on the recommendation so you can track which recommendations have been filed.

<Note>
  Each recommendation can only be pushed to Jira once. If you need to update the issue, edit it directly in Jira.
</Note>

## From Customer Insights

<Tooltip href="https://platform.open.cx/reports/voice-of-customer">Customer Insights</Tooltip> cluster similar feedback across many conversations. A single insight might represent dozens of customers reporting the same friction point.

When an insight reaches critical mass or warrants product action:

1. Open [**Customer Insights**](https://platform.open.cx/reports/voice-of-customer) in your dashboard.
2. Select the insight and click **Push to Jira**.
3. The created issue includes the aggregated evidence — how many customers reported it, representative quotes, and affected conversation links.

This gives your product team a single Jira issue backed by quantified customer demand, not a one-off anecdote.

## From conversations

OpenCX can detect actionable items during live conversations and create Jira issues directly. Common use cases:

<AccordionGroup>
  <Accordion title="Partnership and business requests" icon="handshake">
    When a customer asks about partnerships, enterprise deals, or requests that need a different department's involvement, the AI creates a Jira issue in the appropriate project and continues the conversation — informing the customer that their request has been logged.
  </Accordion>

  <Accordion title="Bug reports from customers" icon="bug">
    When a customer describes a product issue with enough detail, the AI can create a bug report in your engineering project. The issue includes the customer's description, steps to reproduce (when provided), and the full conversation transcript.
  </Accordion>

  <Accordion title="Feature requests during support" icon="wand-magic-sparkles">
    Customers frequently suggest features during support interactions. The AI captures these as structured feature requests in your product backlog, tagged with the conversation context so your team understands the "why" behind the request.
  </Accordion>
</AccordionGroup>

## What the Jira issue looks like

Every issue OpenCX creates contains:

| Field | Content |
| - | - |
| **Summary** | AI-generated title summarizing the feedback, bug, or request. |
| **Description** | Detailed context including the recommendation or insight body, customer quotes, and a **View session in OpenCX** link. |
| **Project** | Your default project, or the override you selected. |
| **Issue type** | Your default type (e.g. Task, Bug, Story), or the override. |
| **Custom fields** | Any fields you've configured in [field mappings](/integrations/jira/connect#configure-field-mappings). |

<Info>
  The **View session in OpenCX** link in the description opens the full conversation transcript, AI reasoning, and tool calls in your [Inbox](https://platform.open.cx/inbox). Your product team can audit any issue back to the exact customer interaction that drove it.
</Info>

## Field mappings in practice

Field mappings configured in your [integration settings](/integrations/jira/connect#configure-field-mappings) apply to every issue OpenCX creates. Use them to:

* Route issues to the right Jira component or label automatically.
* Set priority based on the AI's assessment of severity or customer impact.
* Populate custom fields your team relies on for triage, reporting, or automation.

Mappings only populate fields at creation time. Subsequent updates to the Jira issue are managed by your team in Jira.

## Good to know

<AccordionGroup>
  <Accordion title="One-way sync" icon="arrow-right">
    The integration creates issues in Jira — it does not sync updates from Jira back to OpenCX. Once an issue is created, your team manages it entirely within Jira.
  </Accordion>

  <Accordion title="Deduplication" icon="clone">
    Each recommendation or insight can be pushed to Jira once. OpenCX prevents duplicate issues from the same source. If the same underlying feedback surfaces through multiple insights, they become separate Jira issues.
  </Accordion>

  <Accordion title="Project and issue type selection" icon="folder-open">
    OpenCX loads your available Jira projects and issue types from the Atlassian API. If a project or issue type is missing from the selection, confirm the API token's account has access to it in Jira.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Overview" icon="list-check" href="/integrations/jira/overview">
    What the Jira integration does and supported capabilities.
  </Card>

  <Card title="Connect Jira" icon="plug" href="/integrations/jira/connect">
    Credentials, field mappings, and connection setup.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/jira/troubleshooting">
    Issues not created, wrong project, field mappings missing.
  </Card>

  <Card title="Autopilot" icon="sliders" href="/handoff/topics">
    Configure which topics the AI handles and when it escalates.
  </Card>
</CardGroup>


# Jira overview
Source: https://docs.open.cx/integrations/jira/overview

Turn customer conversations and AI-generated recommendations into structured Jira issues your product team can act on.

<Warning>
  The Jira integration is in **closed beta**. If you'd like early access, contact [support@open.cx](mailto:support@open.cx).
</Warning>

OpenCX turns customer conversations into structured Jira issues. The AI identifies actionable feedback — bug reports, feature requests, partnership inquiries — and creates properly categorized issues in your Jira projects. Your product and engineering teams get a prioritized backlog fed by real customer evidence, without manual triage.

<Tip>
  Setup starts at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard once your organization is enrolled in the beta.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="Issues from customer conversations" icon="comments">
    When the AI detects actionable feedback during a live conversation — a bug report, a feature request, an escalation to another department — it creates a Jira issue with a summary, description, and conversation context attached. Your team sees the customer's words, not a paraphrased ticket.
  </Accordion>

  <Accordion title="Issues from AI Recommendations" icon="lightbulb">
    OpenCX analyzes conversation patterns and surfaces <Tooltip href="https://platform.open.cx/reports/voice-of-customer">AI Recommendations</Tooltip>. Push any recommendation to Jira as a structured issue — the AI writes the summary and description from the underlying conversation evidence.
  </Accordion>

  <Accordion title="Issues from Customer Insights" icon="chart-mixed">
    <Tooltip href="https://platform.open.cx/reports/voice-of-customer">Customer Insights</Tooltip> group similar feedback across many conversations. When an insight reaches critical mass, push it to Jira with the aggregated evidence — one issue backed by dozens of customer voices.
  </Accordion>

  <Accordion title="Smart categorization" icon="tags">
    The AI picks the Jira project, issue type, and priority based on the content. Dropdown fields stay within your existing options. Override any default per issue or set organization-wide defaults in your integration settings.
  </Accordion>

  <Accordion title="Field mappings" icon="table-columns">
    Map OpenCX data to your Jira custom fields. Issue type, priority, labels, and any custom field you define in Jira can be populated automatically when OpenCX creates an issue.
  </Accordion>
</AccordionGroup>

## How conversations become issues

```mermaid theme={"dark"}
flowchart LR
  A[Customer conversation] --> B[AI analyzes]
  B --> C{Actionable?}
  C -- Yes --> D[Recommendation or Insight created]
  D --> E[Push to Jira]
  E --> F[Team works the issue]
  C -- No --> G[AI resolves conversation]
```

## Observability

Every Jira issue OpenCX creates is traceable back to the conversation or recommendation that produced it.

<AccordionGroup>
  <Accordion title="Session link in every issue" icon="link">
    The issue description includes a **View session in OpenCX** link. One click opens the full transcript, AI reasoning, and handoff context in your [OpenCX Inbox](https://platform.open.cx/inbox) — no issue-key lookup required.
  </Accordion>

  <Accordion title="Recommendation and insight traceability" icon="fingerprint">
    Issues created from AI Recommendations or Customer Insights link back to the source. Your product team can trace any Jira issue to the exact conversations and customer evidence that drove it.
  </Accordion>

  <Accordion title="Issue key stored in OpenCX" icon="key">
    OpenCX stores the Jira issue key, ID, and URL on the originating recommendation. Filter recommendations by whether they have a linked Jira issue to track what's been filed and what hasn't.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Jira" icon="plug" href="/integrations/jira/connect">
    Generate an API token, enter credentials, verify the connection.
  </Card>

  <Card title="Issue Flow" icon="diagram-project" href="/integrations/jira/issue-flow">
    How issues are created from recommendations, insights, and conversations.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/jira/troubleshooting">
    Credentials failing, issues not created, field mappings missing.
  </Card>

  <Card title="Handoff" icon="user-group" href="/handoff/introduction">
    How conversations escalate to human agents and downstream integrations.
  </Card>
</CardGroup>


# Jira troubleshooting
Source: https://docs.open.cx/integrations/jira/troubleshooting

Debug Jira connection, issue creation, field mapping, and project access problems.

<Warning>
  The Jira integration is in **closed beta**. If you're not yet enrolled and are seeing issues, contact [support@open.cx](mailto:support@open.cx) for access.
</Warning>

Before debugging, have this ready:

* Your Atlassian Cloud <Tooltip>domain</Tooltip> and the email used for the <Tooltip>API token</Tooltip>.
* The specific recommendation or insight you tried to push to Jira.
* Access to [Settings → Integrations](https://platform.open.cx/settings/integrations) in your OpenCX dashboard.

<Tip>
  Re-run **Verify** in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Jira as your first step. Most issues are credential or permission related.
</Tip>

## Common scenarios

Jump to the symptom that matches what you're seeing.

### **"Failed to verify credentials" on save**

<Tooltip>Likely cause</Tooltip>: wrong domain format, expired token, or mismatched email.

**Fix:**

* Use the **full Atlassian domain** — e.g. `acme.atlassian.net`. The domain must include `atlassian` in the hostname.
* Regenerate the API token in [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens) if the current one may have been revoked.
* Confirm the email matches the Atlassian account that generated the token.

### **Connected but no issues appear in Jira**

<Tooltip>Likely cause</Tooltip>: the API token's account lacks access to the target Jira project, or the default issue type doesn't exist in that project.

**Fix:**

1. Confirm the Atlassian account behind the token has access to the target project in Jira.
2. In OpenCX, check that the **default project** and **default issue type** are set in [Settings → Integrations → Jira](https://platform.open.cx/settings/integrations).
3. Navigate to [**AI Recommendations**](https://platform.open.cx/reports/voice-of-customer) or [**Customer Insights**](https://platform.open.cx/reports/voice-of-customer) and explicitly push an item to Jira. Issues are created on-demand — they are not generated automatically in the background.

<Info>
  Issues are created when you push a recommendation or insight to Jira from the OpenCX dashboard. If you've connected Jira but haven't pushed anything yet, no issues will appear.
</Info>

### **Wrong project or issue type on created issues**

<Tooltip>Likely cause</Tooltip>: organization defaults overriding per-issue selection.

**Fix:** check the defaults in [Settings → Integrations → Jira](https://platform.open.cx/settings/integrations). When pushing a recommendation, use the project and issue type override to target a different project.

### **Field mappings not appearing on issues**

<Tooltip>Likely cause</Tooltip>: mapping not active, field ID mismatch, or the Jira field isn't available on the target issue type's screen.

**Fix:**

1. Open the field mappings in your Jira integration settings and confirm the mapping is saved.
2. In Jira, confirm the custom field is added to the **screen** for the issue type you're creating. Jira hides fields that aren't on the issue's screen, even if the API sets them.
3. Re-push a recommendation to test — field mappings apply at creation time only.

### **Project or issue type missing from the selection**

<Tooltip>Likely cause</Tooltip>: the API token's account doesn't have access to that project, or the issue type isn't available for the selected project.

**Fix:**

* Confirm the Atlassian account has at least **browse** permission on the project.
* Issue types are loaded per project — switch to the correct project to see its available types.

### **None of the above**

If your issue doesn't match any scenario here, contact [support](mailto:support@open.cx) with:

* Your OpenCX organization name.
* The Atlassian domain you're connecting to.
* The specific action you took and the error message (or lack of expected result).

## Limits and timing

| | Value |
| - | - |
| **Issue creation** | On-demand (when you push from the dashboard) |
| **Verification timeout** | 10 seconds |
| **Projects loaded** | Most recent projects from the Atlassian API |
| **Field mappings** | Applied at issue creation time only |
| **Jira Cloud only** | Server and Data Center are not supported |

<Note>
  OpenCX does not retry failed issue creation automatically. If an issue fails to create (e.g. due to a temporary Jira outage), push the recommendation or insight again once Jira is back.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Jira" icon="plug" href="/integrations/jira/connect">
    Re-verify credentials and check field mapping setup.
  </Card>

  <Card title="Issue Flow" icon="diagram-project" href="/integrations/jira/issue-flow">
    How issues are created from recommendations, insights, and conversations.
  </Card>

  <Card title="Overview" icon="list-check" href="/integrations/jira/overview">
    Capabilities and observability features.
  </Card>

  <Card title="Handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and escalation settings.
  </Card>
</CardGroup>


# Pipedrive connect
Source: https://docs.open.cx/integrations/pipedrive/connect

Generate a Pipedrive API token and company domain, then hand both to the Update Lead workflow action.

OpenCX workflows authenticate to Pipedrive with two pieces of data: an <Tooltip href="https://app.pipedrive.com/settings/api">API token</Tooltip> and your <Tooltip>company domain</Tooltip>. Both travel into the workflow action as inputs — there is no org-level connect screen today.

<PipedriveFlow />

<Warning>
  Pipedrive is in **beta**. Confirm with your OpenCX contact that the `Update PipeDrive Lead` action is enabled on your organization before you configure a workflow — otherwise the action will not appear in the flow builder's node picker.
</Warning>

## Generate credentials

<Steps>
  <Step title="Create a dedicated Pipedrive user (recommended)">
    Create a new Pipedrive user scoped to the pipelines OpenCX should touch. The API token inherits the user's permissions — a narrowly-scoped user limits blast radius if the token leaks.
  </Step>

  <Step title="Generate an API token">
    Sign in as that user, open **Personal preferences → API**, and copy the token. Full URL: [https://app.pipedrive.com/settings/api](https://app.pipedrive.com/settings/api).

    <Warning>
      Anyone with the token can read and write every record the user can see. Treat it like a password.
    </Warning>
  </Step>

  <Step title="Copy your company domain">
    Look at your Pipedrive URL. The first part — `yourcompany` in `yourcompany.pipedrive.com` — is the domain you need. Do not include `.pipedrive.com` or `https://`.
  </Step>

  <Step title="Store both somewhere safe">
    Drop both into your password manager or secret store. Every workflow node that touches Pipedrive expects them as inputs, so you will reuse them across flows.
  </Step>
</Steps>

<Info>
  OpenCX does not persist Pipedrive credentials at the organization level yet. Each workflow action reads the token and domain from its own configuration — rotating the token means updating every workflow that uses it.
</Info>

## Verify the connection

Before wiring credentials into a production workflow, smoke-test them:

<Steps>
  <Step title="Pick a throwaway lead">
    Open Pipedrive, create a test lead (or grab one you know is safe to touch), and copy its **Lead ID** from the URL.
  </Step>

  <Step title="Build a one-node workflow">
    In [your OpenCX dashboard](https://platform.open.cx), create a workflow with a manual trigger and a single **Update PipeDrive Lead** node. Paste the API token, company domain, and the Lead ID.
  </Step>

  <Step title="Add one field update">
    Set `fieldKey` to `title` and `value` to anything (e.g. `"OpenCX smoke test"`).
  </Step>

  <Step title="Run and confirm">
    Run the workflow. The action output should return `success: true` and the lead's title should reflect the new value in Pipedrive. If it doesn't, jump to [Troubleshooting](/integrations/pipedrive/troubleshooting).
  </Step>
</Steps>

***

## Related Documentation

<CardGroup>
  <Card title="Update Lead Action" icon="user-round-pen" href="/integrations/pipedrive/update-lead-action">
    Full reference for the Update PipeDrive Lead workflow action.
  </Card>

  <Card title="Trigger workflows from Pipedrive" icon="bolt" href="/integrations/pipedrive/webhook-trigger">
    Wire Pipedrive automations into an OpenCX workflow.
  </Card>

  <Card title="Overview" icon="users-viewfinder" href="/integrations/pipedrive/overview">
    Capabilities and patterns at a glance.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/pipedrive/troubleshooting">
    Credentials rejected, lead not found, field update errors.
  </Card>
</CardGroup>


# Pipedrive overview
Source: https://docs.open.cx/integrations/pipedrive/overview

Keep Pipedrive leads current from OpenCX workflows, and trigger AI phone calls when new leads land in your pipeline.

OpenCX connects to Pipedrive through workflows. Update a <Tooltip>lead</Tooltip> as an AI conversation progresses, or have Pipedrive kick off an OpenCX workflow — most commonly an outbound AI phone call — the moment a new lead appears.

<Info>
  Pipedrive is currently in **beta**. Reach out to your OpenCX contact to enable the workflow action on your organization. There is no self-service connect screen today — [**Settings → Integrations**](https://platform.open.cx/settings/integrations) shows Pipedrive as "coming soon" until support enables it.
</Info>

## What you get

<AccordionGroup>
  <Accordion title="Keep your pipeline current as conversations close" icon="user-pen">
    When an AI conversation confirms a budget, a move-in date, or any detail your reps need, a workflow writes the value straight back to the matching Pipedrive lead. No CSV exports, no manual data entry, no duplicate records.
  </Accordion>

  <Accordion title="Trigger AI outbound calls when a lead lands" icon="phone-arrow-up-right">
    Pipedrive automation sends the new lead's phone, name, and custom fields into an OpenCX workflow. The workflow places an AI phone call with the lead's context already loaded — the agent greets them by name and works your script.
  </Accordion>

  <Accordion title="Reach leads by phone, email, person, or org name" icon="magnifying-glass">
    When you already have a <Tooltip>Lead ID</Tooltip>, the workflow updates that lead directly. When you don't, OpenCX searches Pipedrive by phone number, email, person name, or org name.
  </Accordion>
</AccordionGroup>

## Pick your pattern

Most teams run both patterns side by side — Pipedrive drives the first touchpoint, OpenCX keeps the lead current from then on.

<Tabs>
  <Tab title="OpenCX updates Pipedrive">
    An AI workflow finishes a conversation and writes the outcome back to Pipedrive — stage, value, custom fields, or a fresh title. Use the `Update PipeDrive Lead` workflow action.

    <Card title="Update Lead Action" icon="user-round-pen" href="/integrations/pipedrive/update-lead-action">
      Configure the action, search by phone or email, update or create leads.
    </Card>
  </Tab>

  <Tab title="Pipedrive triggers OpenCX">
    A Pipedrive automation fires on "lead created" (or any other trigger) and POSTs the lead into an OpenCX <Tooltip>Form Submit trigger</Tooltip>. The workflow then places an outbound AI phone call, runs a custom branch, or whatever else you need.

    <Card title="Trigger workflows from Pipedrive" icon="bolt" href="/integrations/pipedrive/webhook-trigger">
      Wire a Pipedrive automation into an OpenCX workflow with a typed payload.
    </Card>
  </Tab>
</Tabs>

***

## Related Documentation

<CardGroup>
  <Card title="Connect" icon="plug" href="/integrations/pipedrive/connect">
    Grab your Pipedrive API token and company domain.
  </Card>

  <Card title="Update Lead Action" icon="user-round-pen" href="/integrations/pipedrive/update-lead-action">
    Push conversation outcomes into Pipedrive leads.
  </Card>

  <Card title="Trigger workflows from Pipedrive" icon="bolt" href="/integrations/pipedrive/webhook-trigger">
    Start an OpenCX workflow from a Pipedrive automation.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/pipedrive/troubleshooting">
    Lead not found, phone-format errors, empty update fields.
  </Card>
</CardGroup>


# Pipedrive troubleshooting
Source: https://docs.open.cx/integrations/pipedrive/troubleshooting

Debug Pipedrive workflow errors: payloads that arrive untyped, E.164 phone failures, empty update errors, and search misses.

Before debugging, have this ready:

* The **workflow run ID** from your [OpenCX dashboard](https://platform.open.cx) (run viewer → failed run).
* The **Pipedrive Lead ID** involved, if known.
* The **form ID** if the workflow uses a Form Submit trigger, or the generic webhook URL otherwise.

<Tip>
  The workflow run viewer shows each node's input and output. Most Pipedrive failures surface there as an `error` string on the action — read it before assuming the integration is down.
</Tip>

## Common scenarios

Jump to the symptom you're seeing.

### **Pipedrive webhook fires but the workflow doesn't see the body**

<Tooltip>Likely cause</Tooltip>: the workflow uses a generic **Webhook** trigger instead of a **Form Submit** trigger.

**Fix:** switch the trigger type to **Form Submit** and define the schema for the fields Pipedrive sends. Update the Pipedrive HTTP Request body to `{ formId, formData: { ... } }` and POST to `https://api.open.cx/backend/workflow/form-submission`. Full recipe in [Trigger workflows from Pipedrive](/integrations/pipedrive/webhook-trigger).

### **Outbound call fails with `customer.number must be a valid phone number in the E.164 format`**

<Tooltip>Likely cause</Tooltip>: the phone number coming out of Pipedrive lacks a `+` prefix or a country code.

**Fix:** normalize the number before the call action runs. Prepend `+` in the Pipedrive HTTP Request body if it's missing, or add a transformation node in the OpenCX workflow between the trigger and the call action that rewrites the number to E.164.

### **`Update PipeDrive Lead` action returns "Lead not found and createIfNotFound is false"**

<Tooltip>Likely cause</Tooltip>: the search criterion either doesn't match exactly or points at a custom field.

**Fix:** search by a standard field — `phone`, `email`, `person_name`, or `org_name`. If you absolutely need a custom-field match, pass the Lead ID directly into the workflow (for example, include it in the Pipedrive automation payload and route it through the trigger) and skip Search Criteria. Enable **Create If Not Found** only when creating a duplicate is actually safe.

### **Action fails with "No valid fields to update"**

<Tooltip>Likely cause</Tooltip>: all the values resolved empty (often because upstream data was missing) and **Skip Empty Values** is on.

**Fix:** guard the node with a condition so it only runs when you have at least one non-empty value. If you intentionally want to clear fields in Pipedrive, set **Skip Empty Values** to `false` so empty strings and `null`s are sent through.

### **None of the above**

Send your OpenCX contact the failing **workflow run ID**, the **Lead ID** you're touching, and a copy of the node configuration (redact the API token). We'll trace from there.

## Limits & timing

| | Value |
| - | - |
| **Per-action HTTP timeout** | 30 seconds for each Pipedrive API call (search, create, update) |
| **Pipedrive API rate limit** | Governed by your Pipedrive plan — see your plan's rate-limit docs |

<Note>
  Bursts from a single Pipedrive automation can exceed plan rate limits during data backfills. Stagger the HTTP Request step or throttle the automation when migrating large lead batches.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect" icon="plug" href="/integrations/pipedrive/connect">
    Re-verify the API token and company domain.
  </Card>

  <Card title="Update Lead Action" icon="user-round-pen" href="/integrations/pipedrive/update-lead-action">
    Inputs, search rules, and the value-field quirk.
  </Card>

  <Card title="Trigger workflows from Pipedrive" icon="bolt" href="/integrations/pipedrive/webhook-trigger">
    Form Submit vs webhook, E.164 normalization, automation setup.
  </Card>

  <Card title="Overview" icon="users-viewfinder" href="/integrations/pipedrive/overview">
    Capabilities and patterns at a glance.
  </Card>
</CardGroup>


# Update Lead Action
Source: https://docs.open.cx/integrations/pipedrive/update-lead-action

Find a Pipedrive lead by ID, phone, email, person, or org, and update or create it from an OpenCX workflow.

The **Update PipeDrive Lead** action lives inside the workflow builder. Point it at a lead (by ID or by search), declare the fields to change, and run. If the lead doesn't exist, the action can create one.

<Tip>
  New to the workflow builder? Open your [OpenCX dashboard](https://platform.open.cx) and pick any existing workflow, then drop an `Update PipeDrive Lead` node from the **CRM** category in the node picker.
</Tip>

## Configure the action

<Steps>
  <Step title="Drop the node into your workflow">
    In the flow builder, add an `Update PipeDrive Lead` node wherever you want the update to fire — usually after the AI has collected enough context.
  </Step>

  <Step title="Paste your credentials">
    Fill **PipeDrive API Token** and **Company Domain** with the values you gathered in [Connect](/integrations/pipedrive/connect).
  </Step>

  <Step title="Decide how to find the lead">
    If the workflow already has a Lead ID (from a Pipedrive webhook, for example), pass it in the **Lead ID** field. Otherwise fill **Search Criteria** with one or more `{ field, value }` pairs.
  </Step>

  <Step title="Declare your field updates">
    List the fields you want to write in **Field Updates**. Each entry is a `{ fieldKey, value }` pair — use Pipedrive's own field keys (`title`, `value`, `expected_close_date`) or the key of any custom field.
  </Step>

  <Step title="Pick your fallback behavior">
    Enable **Create If Not Found** if the workflow should create a new lead when the search misses. Leave **Skip Empty Values** on to avoid accidentally clearing fields.
  </Step>
</Steps>

## Inputs reference

<AccordionGroup>
  <Accordion title="Lead ID" icon="fingerprint">
    Optional. If set, the action skips the search entirely and PATCHes that lead. Use this when the Lead ID is already on your session or was passed in from a Pipedrive automation payload.
  </Accordion>

  <Accordion title="Search Criteria" icon="magnifying-glass">
    Optional, used only when Lead ID is empty. The first criterion's value becomes the search term; <Tooltip>Pipedrive's item search</Tooltip> is called with `exact_match=true` on `lead` items. Stick to standard fields: `phone`, `email`, `person_name`, or `org_name`.

    <Warning>
      Searching by **custom fields** is unreliable. If your lead needs to be matched by a value you stored in a custom field, find it a different way — for example, include the Lead ID in your Pipedrive automation payload and pass it through the workflow instead.
    </Warning>
  </Accordion>

  <Accordion title="Field Updates" icon="pen-to-square">
    Required. An array of `{ fieldKey, value }` objects. Each `fieldKey` is Pipedrive's exact field key — standard fields (`title`, `value`, `expected_close_date`) or the custom-field key you can see in Pipedrive's field settings.
  </Accordion>

  <Accordion title="Create If Not Found" icon="plus">
    Defaults to `false`. When `true` and the search misses, the action creates a new lead using your Field Updates as its starting values. If you didn't pass a `title`, OpenCX sets one from the first search criterion's value (e.g. `Lead - +15551234567`).
  </Accordion>

  <Accordion title="Skip Empty Values" icon="filter">
    Defaults to `true`. When `true`, fields whose value is `null`, `undefined`, or `""` are dropped before the update — they never overwrite existing data in Pipedrive. Set to `false` only when you explicitly want to clear a field.
  </Accordion>
</AccordionGroup>

## Updating the deal value

Pipedrive stores the `value` field as an object with an amount and a currency. The action hides that detail when you pass a plain number — it auto-wraps `42` as `{ amount: 42, currency: "USD" }`.

If your pipeline uses a different currency, pass the full object yourself:

```json theme={"dark"}
{
  "fieldKey": "value",
  "value": { "amount": 42, "currency": "EUR" }
}
```

For other numeric fields (stages, enums, sets), Pipedrive expects strings. The action stringifies them automatically — pass `3` and the API receives `"3"`.

## Output

| Key | Meaning |
| - | - |
| `success` | `true` when the update or create landed; `false` if the action returned an error. |
| `leadId` | The ID of the lead that was updated or created. |
| `wasCreated` | `true` if the action created a new lead; `false` if it updated an existing one. |
| `updatedFields` | Array of the `fieldKey`s that actually went into the request body. |
| `leadData` | The full lead object returned by Pipedrive after the write. Use it to chain follow-up nodes. |
| `error` | Error message if `success` is `false`. |

## Good To Know

<AccordionGroup>
  <Accordion title="Per-call timeout" icon="clock">
    Each search, create, and update request has a hard **30-second timeout**. Pipedrive is usually well under that, but flag slow runs if you see timeouts in your workflow run viewer.
  </Accordion>

  <Accordion title="Workflow-scoped credentials" icon="key">
    The API token is read from the node's own configuration every time the workflow runs — it is not stored at the organization level. Rotate a token and you will need to update every node that references it.
  </Accordion>

  <Accordion title="Errors surface as run failures" icon="triangle-exclamation">
    A bad token, a missing lead with `Create If Not Found` disabled, or an all-empty update raises a runtime error. The workflow run fails on that node — handle it with a conditional branch if your flow needs to keep going.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Connect" icon="plug" href="/integrations/pipedrive/connect">
    Generate an API token and find your company domain.
  </Card>

  <Card title="Trigger workflows from Pipedrive" icon="bolt" href="/integrations/pipedrive/webhook-trigger">
    Pair this action with a Pipedrive automation that fires the workflow.
  </Card>

  <Card title="Overview" icon="users-viewfinder" href="/integrations/pipedrive/overview">
    Capabilities and patterns at a glance.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/pipedrive/troubleshooting">
    Lead not found, empty updates, currency errors.
  </Card>
</CardGroup>


# Trigger workflows from Pipedrive
Source: https://docs.open.cx/integrations/pipedrive/webhook-trigger

Fire an OpenCX workflow from a Pipedrive automation — typed payload, outbound phone calls, lead-by-lead branching.

Pipedrive automations can POST a new lead into an OpenCX workflow the moment it appears in the pipeline. The workflow can then place an outbound AI call, branch on custom fields, or enrich the lead with data from another system.

<Tip>
  Use a **Form Submit** trigger in OpenCX, not a generic webhook. Form Submit triggers validate the payload against a schema you define — the workflow builder then shows typed suggestions (`trigger.formData.phone`, `trigger.formData.name`) instead of a free-form blob.
</Tip>

## How it flows

```mermaid theme={"dark"}
flowchart LR
    A[New lead in Pipedrive] --> B[Pipedrive automation]
    B --> C[HTTP Request step]
    C --> D[OpenCX Form Submit trigger]
    D --> E[Outbound AI call or lead update]
```

## Build the OpenCX side first

<Steps>
  <Step title="Create a workflow with a Form Submit trigger">
    In your [OpenCX dashboard](https://platform.open.cx), start a new workflow and pick **Form Submit** as the trigger type.
  </Step>

  <Step title="Define the form schema">
    Add one field per value Pipedrive will send. Typical set for an outbound-call flow: `name`, `email`, `phone_number`, plus any custom fields (`booking_code`, `van_model`, `lead_id`). The field names here become the keys in `formData` on the Pipedrive side — keep them identical.
  </Step>

  <Step title="Copy the form ID">
    The trigger node exposes a **Form ID** (a ULID like `01K9SYWVMSJF5PT4AH4ACHV3F3`). Copy it — Pipedrive will send it alongside the payload.
  </Step>

  <Step title="Finish the flow">
    After the trigger, add whatever nodes you need. Common chains: `Make Outbound Call` for phone follow-up, or `Update PipeDrive Lead` to enrich the lead after a downstream action lands.
  </Step>
</Steps>

## Wire Pipedrive's automation

<Steps>
  <Step title="Open Pipedrive Automations">
    Go to [Pipedrive Automations](https://app.pipedrive.com/automations) and create a new workflow.
  </Step>

  <Step title="Pick your trigger">
    For outbound calls on new leads, use **Lead created**. For updates on stage changes, use **Lead updated → Stage**. Any Pipedrive trigger works.
  </Step>

  <Step title="Add an HTTP Request action">
    Pipedrive's automation builder has a built-in **HTTP Request** step. Configure it as:

    * **Method:** `POST`
    * **URL:** `https://api.open.cx/backend/workflow/form-submission`
    * **Headers:** `Content-Type: application/json`
    * **Body:**

    ```json theme={"dark"}
    {
      "formId": "01K9SYWVMSJF5PT4AH4ACHV3F3",
      "formData": {
        "name": "{{Lead.person_name}}",
        "email": "{{Lead.person_email}}",
        "phone_number": "{{Lead.person_phone}}",
        "lead_id": "{{Lead.id}}"
      }
    }
    ```

    Replace `formId` with the ID you copied from OpenCX, and swap the merge tags for the Pipedrive fields you want to send.
  </Step>

  <Step title="Save and test">
    Create a test lead in Pipedrive. Your OpenCX workflow should fire within seconds — check the run viewer in the dashboard to confirm the payload arrived typed.
  </Step>
</Steps>

## Outbound call payloads need E.164 phone numbers

If the next step is an outbound AI call, the phone number has to be in <Tooltip>E.164</Tooltip> format before the call action runs. Pipedrive often stores phone numbers without a leading `+`, which the call provider rejects with `customer.number must be a valid phone number in the E.164 format`.

Two places to fix it:

* **In Pipedrive's HTTP Request body** — concatenate a `+` if the number doesn't start with one. If Pipedrive's automation builder doesn't support string manipulation for your layout, fix it upstream.
* **In the OpenCX workflow** — add a transformation node between the trigger and the call action that prefixes `+` when missing.

<Warning>
  Don't skip this. A missing `+` is the single most common reason calls fire from Pipedrive but never ring through — see [Troubleshooting](/integrations/pipedrive/troubleshooting).
</Warning>

## Form Submit vs generic webhook

You can also start a workflow from a generic **Webhook** trigger. It works — but the payload comes through as an untyped object, and the flow builder can't suggest fields. For anything beyond a proof of concept, use Form Submit.

| | Form Submit | Generic Webhook |
| - | - | - |
| Payload shape | Enforced against your schema | Free-form JSON |
| Builder suggestions | Typed (`trigger.formData.phone`) | Untyped |
| URL | `api.open.cx/backend/workflow/form-submission` | Unique per trigger |
| Body wrapper | `{ formId, formData }` | Whatever you send |

***

## Related Documentation

<CardGroup>
  <Card title="Update Lead Action" icon="user-round-pen" href="/integrations/pipedrive/update-lead-action">
    Pair a Pipedrive-triggered workflow with a write-back to the same lead.
  </Card>

  <Card title="Connect" icon="plug" href="/integrations/pipedrive/connect">
    Credentials for the write-back side.
  </Card>

  <Card title="Overview" icon="users-viewfinder" href="/integrations/pipedrive/overview">
    Capabilities and patterns at a glance.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/pipedrive/troubleshooting">
    Payload untyped, phone-format errors, workflow not firing.
  </Card>
</CardGroup>


# AI Email in Salesforce
Source: https://docs.open.cx/integrations/salesforce/channels/email

Create Salesforce Cases from every email handoff so your reps work them from the console they already live in.

Email is the one channel that routes through [Case Management](/integrations/salesforce/email-cases), not Live Messaging. Every email handoff creates (or appends to) a Salesforce <Tooltip>Case</Tooltip> so your reps work email the way Salesforce is designed to handle it — Cases with assignees, queues, and status tracking.

## Pre-requisites

<Warning>
  **Set up email forwarding first.** No email handoff has anything to Case until inbound mail is reaching OpenCX — start with [Connect Email](/email/forwarding) and come back here.
</Warning>

* **Email forwarding configured** — see [Connect Email](/email/forwarding).
* **Salesforce Email Cases credentials, webhook, and Apex configured** — see [Email Cases setup](/integrations/salesforce/email-cases).

## How conversations land in Salesforce

```mermaid theme={"dark"}
flowchart LR
  A[Customer emails your support address] --> B[AI replies from the same address]
  B --> C{AI can resolve?}
  C -- Yes --> D[Thread stays email-only]
  C -- No --> E[Handoff]
  E --> F[Salesforce Case created with transcript]
  F --> G[Rep replies on Case — lands in customer inbox]
```

## Setting up

<Steps>
  <Step title="Confirm email forwarding works">
    Open [**Channels → AI Email**](https://platform.open.cx/channels/configure/mail) in the OpenCX dashboard. Your forwarding address should be listed and verified. Send a test email and confirm it reaches the [Inbox](https://platform.open.cx/inbox).
  </Step>

  <Step title="Confirm Salesforce Email Cases is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **Salesforce → Email**. The status should show **Connected** and the webhook URL should be displayed.
  </Step>

  <Step title="Confirm the Apex trigger is active">
    In Salesforce, go to **Setup → Apex Triggers** and verify the `CaseTrigger` fires on `Case (after insert)`. See [Email Cases setup](/integrations/salesforce/email-cases#configure-the-webhook-in-salesforce) for the exact code.
  </Step>

  <Step title="Trigger a test handoff">
    Send a test email to your connected address and respond with something that causes the AI to escalate. Alternatively, go to the [Inbox](https://platform.open.cx/inbox) and manually hand off the session.
  </Step>

  <Step title="Verify the Case in Salesforce">
    A Case should appear in Salesforce. Check:

    * The **conversation summary** is the Case description.
    * The **full transcript** is attached as Case comments.
    * `Case_From__c` is set to `opencx`.
    * The OpenCX session shows a `salesforce_case_id` linking to this Case.
  </Step>

  <Step title="Reply and verify sync">
    Reply on the Case from Salesforce. Confirm it arrives in the customer's email and shows as an agent message in the [OpenCX Inbox](https://platform.open.cx/inbox).
  </Step>
</Steps>

## What the rep sees

* A **Salesforce Case** with `Case_From__c` set to `opencx`.
* Conversation **summary as the description**, full transcript as Case comments.
* The OpenCX session linked via `salesforce_case_id` — visible in the [Inbox](https://platform.open.cx/inbox) session detail for tracing.
* Replies on the Case sync back to the contact's inbox.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Case-append on returning contacts" icon="rotate">
    If the same contact re-engages before the Case is closed, OpenCX appends to the existing Case instead of opening a new one. Your reps keep context; your reports don't inflate.
  </Accordion>

  <Accordion title="Rep reply syncs back to the customer's inbox" icon="reply">
    When your rep replies on the Case, the webhook fires and OpenCX delivers the reply to the customer's original email thread. The AI stops auto-responding once a human agent is active on the session.
  </Accordion>

  <Accordion title="Attachments" icon="paperclip">
    Attachments the customer sends by email are included in the OpenCX session. Attachments your rep adds to a Case reply sync back through the customer's email thread (subject to your email provider's attachment limits).
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Email Support" icon="envelope" href="/email/introduction">
    The channel itself — forwarding setup, flow, troubleshooting.
  </Card>

  <Card title="Email Cases setup" icon="plug" href="/integrations/salesforce/email-cases">
    OAuth, Connected App, webhook, and Apex configuration.
  </Card>

  <Card title="Salesforce overview" icon="cloud" href="/integrations/salesforce/overview">
    What Salesforce lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/salesforce/troubleshooting">
    Cases not created, replies not syncing.
  </Card>
</CardGroup>


# AI Phone Support in Salesforce
Source: https://docs.open.cx/integrations/salesforce/channels/phone

Route phone conversations from OpenCX into the Salesforce console with full transcript and handoff context.

Phone conversations route through <Tooltip>Messaging for In-App and Web</Tooltip>. When the AI phone agent hands off a call, your rep picks it up as a conversation in the Salesforce console — with the full transcript attached and a clear handoff reason.

## Pre-requisites

<Warning>
  **Create your AI Phone agent first.** No calls can hand off until the agent exists and a number is bound to it — start with [Create Phone Agent](/phone/create-agent) and come back here.
</Warning>

* **AI Phone agent created and reachable on a number** — see [Create Phone Agent](/phone/create-agent) and [Inbound calls](/phone/inbound-calls).
* **Salesforce Live Messaging credentials saved** — see [Live Messaging setup](/integrations/salesforce/live-messaging).

## How conversations land in Salesforce

```mermaid theme={"dark"}
flowchart LR
  A[Caller dials your number] --> B[AI voice agent answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Call ends]
  C -- No --> E[Handoff]
  E --> F[Conversation + transcript in Salesforce]
  F --> G[Rep follows up on preferred channel]
```

## Setting up

<Steps>
  <Step title="Confirm the phone agent is live">
    Open [**Channels → Phone**](https://platform.open.cx/channels/phone) in the OpenCX dashboard. Your AI Phone agent should appear with an active number. Test a call to confirm the agent answers.
  </Step>

  <Step title="Confirm Live Messaging is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **Salesforce → MIAW**. All six fields should be filled and saved.
  </Step>

  <Step title="Trigger a test handoff">
    Call the agent's number and say something like *"I need to speak with a person."* The AI should hand off.
  </Step>

  <Step title="Verify in the Salesforce console">
    The conversation should appear with the **full call transcript** attached. Confirm that routing attributes including `OpencxSessionId` are present, and that the handoff reason summary is visible.
  </Step>
</Steps>

## What the rep sees

* A **conversation in the Salesforce console** routed through Omni-Channel.
* The **full call transcript** (AI and caller, with timestamps) attached as messages on the conversation.
* `OpencxSessionId` routing attribute — the trace key to the recording and full debug view in OpenCX.
* The handoff reason (what the caller asked for, what the AI couldn't resolve) in the conversation summary.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Transcript timing" icon="clock">
    The transcript is attached at handoff time, not live during the call. Reps see the conversation appear within a few seconds of the transfer or escalation flag.
  </Accordion>

  <Accordion title="Live transfer vs logged escalation" icon="arrow-right-arrow-left">
    Two handoff modes:

    * **Live transfer** — the AI bridges the caller to a configured phone number. The caller stays on the line. A Salesforce conversation still gets created with the transcript so your rep has context.
    * **Logged escalation** — the AI ends the call and creates the Salesforce conversation for a rep to follow up on a channel the caller prefers (email, SMS, callback).

    Configure the handoff phone number per agent at [**Channels → Phone**](https://platform.open.cx/channels/phone) → select the agent → **Agent Configuration**.
  </Accordion>

  <Accordion title="Caller identity" icon="id-card">
    When the caller is already a known OpenCX contact (matched by phone number), the identity token is authenticated. Unknown callers get an unauthenticated token with just the phone number until they identify further.
  </Accordion>

  <Accordion title="Recordings and OpenCX-side debug" icon="volume-high">
    Audio recordings and per-turn AI reasoning live on the OpenCX side. The session detail in the [Inbox](https://platform.open.cx/inbox) opens the full playback, reasoning trace, and any tool calls the AI made during the call.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Phone Support" icon="phone" href="/phone/introduction">
    The channel itself — create the agent, configure, inbound and outbound.
  </Card>

  <Card title="Live Messaging setup" icon="plug" href="/integrations/salesforce/live-messaging">
    JWT credentials, routing attributes, and connection.
  </Card>

  <Card title="Salesforce overview" icon="cloud" href="/integrations/salesforce/overview">
    What Salesforce lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/salesforce/troubleshooting">
    Transcript missing, handoff not creating conversation.
  </Card>
</CardGroup>


# AI SMS Support in Salesforce
Source: https://docs.open.cx/integrations/salesforce/channels/sms

Route inbound SMS conversations from OpenCX into the Salesforce console as live messaging threads.

SMS conversations route through <Tooltip>Messaging for In-App and Web</Tooltip>. When the AI hands off an SMS thread, your rep picks it up as a live messaging thread in the Salesforce console and replies on the same number the customer texted.

## Pre-requisites

<Warning>
  **Connect and verify your SMS number first.** No inbound SMS can reach OpenCX until the channel is live — start with [Connect SMS](/sms/connect-sms) and come back here.
</Warning>

* **SMS number connected and verified** — see [Connect SMS](/sms/connect-sms) and, for US numbers, [SMS compliance](/sms/compliance).
* **Salesforce Live Messaging credentials saved** — see [Live Messaging setup](/integrations/salesforce/live-messaging).

## How conversations land in Salesforce

```mermaid theme={"dark"}
flowchart LR
  A[Customer texts your SMS number] --> B[AI replies via SMS]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation closes]
  C -- No --> E[Handoff via Live Messaging]
  E --> F[Messaging thread in Salesforce]
  F --> G[Rep replies — lands as SMS]
```

## Setting up

<Steps>
  <Step title="Confirm SMS is connected">
    Open [**Channels → SMS**](https://platform.open.cx/channels/sms) in the OpenCX dashboard. Your SMS number should be listed and active.
  </Step>

  <Step title="Confirm Live Messaging is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **Salesforce → MIAW**. All six fields should be filled and saved.
  </Step>

  <Step title="Trigger a test handoff">
    Text your connected number and ask to speak to a human. The AI should hand off.
  </Step>

  <Step title="Verify in the Salesforce console">
    The conversation should appear as a **messaging thread** with the full AI transcript. Reply from Salesforce and confirm the response lands as an SMS on the customer's phone.
  </Step>
</Steps>

## What the rep sees

* A **messaging thread in the Salesforce console** routed through Omni-Channel.
* Contact phone number in the conversation.
* Full transcript of the AI-to-customer exchange.
* `OpencxSessionId` routing attribute — the trace key to the full OpenCX session.
* Replies deliver as SMS within a couple of seconds, carrier willing.

## Channel-specific details

<AccordionGroup>
  <Accordion title="US number compliance" icon="flag">
    US SMS numbers require <Tooltip>10DLC registration</Tooltip> or <Tooltip>toll-free verification</Tooltip> before they can reliably deliver outbound messages. Complete this on the OpenCX side — see [SMS compliance](/sms/compliance). The Salesforce integration doesn't change the requirement.
  </Accordion>

  <Accordion title="Contact matching by phone number" icon="phone">
    OpenCX matches contacts primarily on phone number. Email is used only when the customer has shared one on another channel first.
  </Accordion>

  <Accordion title="Message length and segmentation" icon="ruler">
    SMS messages are split into 160-character segments by carriers. Reps in the Salesforce console don't see the split — the full reply is sent as one logical message and the customer sees it as one thread. Keep replies tight; carrier costs scale per segment.
  </Accordion>

  <Accordion title="MMS" icon="image">
    Media sent by the customer (MMS) appears as attachments on the messaging thread when the carrier supports it. Outbound MMS support depends on your SMS provider's capabilities.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI SMS Support" icon="comment-sms" href="/sms/introduction">
    The channel itself — connect, routing, compliance.
  </Card>

  <Card title="Live Messaging setup" icon="plug" href="/integrations/salesforce/live-messaging">
    JWT credentials, routing attributes, and connection.
  </Card>

  <Card title="Salesforce overview" icon="cloud" href="/integrations/salesforce/overview">
    What Salesforce lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/salesforce/troubleshooting">
    Replies not reaching SMS, routing issues.
  </Card>
</CardGroup>


# AI WhatsApp Support in Salesforce
Source: https://docs.open.cx/integrations/salesforce/channels/whatsapp

Route WhatsApp Business conversations from OpenCX into the Salesforce console as live messaging threads.

WhatsApp conversations route through <Tooltip>Messaging for In-App and Web</Tooltip>. When the AI hands off a WhatsApp thread, your rep picks it up as a live messaging thread in the Salesforce console and replies on the same number the customer wrote in on.

## Pre-requisites

<Warning>
  **Connect your WhatsApp Business number first.** No WhatsApp messages can reach OpenCX until the channel is live — start with [Connect WhatsApp](/whatsapp/connect-whatsapp) and come back here.
</Warning>

* **WhatsApp Business number connected** — see [Connect WhatsApp](/whatsapp/connect-whatsapp).
* **Salesforce Live Messaging credentials saved** — see [Live Messaging setup](/integrations/salesforce/live-messaging).

## How conversations land in Salesforce

```mermaid theme={"dark"}
flowchart LR
  A[Customer messages your WhatsApp number] --> B[AI replies on WhatsApp]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation closes]
  C -- No --> E[Handoff via Live Messaging]
  E --> F[Messaging thread in Salesforce]
  F --> G[Rep replies — lands on WhatsApp]
```

## Setting up

<Steps>
  <Step title="Confirm WhatsApp is connected">
    Open [**Channels → WhatsApp**](https://platform.open.cx/channels/whatsapp) in the OpenCX dashboard. Your WhatsApp Business number should be listed and active.
  </Step>

  <Step title="Confirm Live Messaging is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **Salesforce → MIAW**. All six fields should be filled and saved.
  </Step>

  <Step title="Trigger a test handoff">
    Send a WhatsApp message to your connected number and ask to speak to a human. The AI should hand off.
  </Step>

  <Step title="Verify in the Salesforce console">
    The conversation should appear as a **messaging thread** with the full AI transcript. Reply from Salesforce and confirm the response lands on the customer's WhatsApp.
  </Step>
</Steps>

## What the rep sees

* A **messaging thread in the Salesforce console** routed through Omni-Channel.
* The contact's WhatsApp profile (name, phone number) in the conversation.
* Full transcript of the AI-to-customer exchange so far.
* `OpencxSessionId` routing attribute — the trace key to the full OpenCX session.
* Replies land on the customer's WhatsApp within a couple of seconds.

## Channel-specific details

<AccordionGroup>
  <Accordion title="24-hour messaging window" icon="clock">
    WhatsApp's policy lets reps send free-form messages within 24 hours of the customer's last message. Outside that window, replies must use an approved <Tooltip>message template</Tooltip>. Your rep will need to use templates from the WhatsApp side if the window has closed.
  </Accordion>

  <Accordion title="Contact matching by phone number" icon="phone">
    OpenCX matches contacts primarily on phone number. If the customer has previously shared an email, that link is preserved. No duplicate contact records.
  </Accordion>

  <Accordion title="Media messages" icon="image">
    Images, audio, and documents the customer sends on WhatsApp appear as attachments on the messaging thread in the Salesforce console. Size limits follow WhatsApp's per-media-type limits.
  </Accordion>

  <Accordion title="Proactive outbound" icon="paper-plane">
    Sending a WhatsApp template-message campaign from OpenCX is independent of the Salesforce integration — see the [WhatsApp channel docs](/whatsapp/introduction). Replies to a template land as a messaging thread in the Salesforce console once the customer engages.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI WhatsApp Support" icon="whatsapp" href="/whatsapp/introduction">
    The channel itself — connect, messaging rules, templates.
  </Card>

  <Card title="Live Messaging setup" icon="plug" href="/integrations/salesforce/live-messaging">
    JWT credentials, routing attributes, and connection.
  </Card>

  <Card title="Salesforce overview" icon="cloud" href="/integrations/salesforce/overview">
    What Salesforce lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/salesforce/troubleshooting">
    Conversations not appearing, replies not reaching WhatsApp.
  </Card>
</CardGroup>


# AI Chat Widget in Salesforce
Source: https://docs.open.cx/integrations/salesforce/channels/widget

Route web chat conversations from the AI Chat Widget into the Salesforce console as live messaging threads.

Widget conversations route through <Tooltip>Messaging for In-App and Web</Tooltip>. When the AI hands off a chat, your rep picks it up as a live messaging thread inside the Salesforce console — no ticket created, no context lost.

## Pre-requisites

<Warning>
  **Install the AI Chat Widget on your site first.** Salesforce handoff has nothing to route until the widget is live — start with [Install Widget](/widget/install-widget) and come back here.
</Warning>

* **Widget installed and reachable** — see [Install Widget](/widget/install-widget).
* **Salesforce Live Messaging credentials saved** — see [Live Messaging setup](/integrations/salesforce/live-messaging).

## How conversations land in Salesforce

```mermaid theme={"dark"}
flowchart LR
  A[Visitor opens widget] --> B[AI answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Visitor closes the chat]
  C -- No --> E[Handoff via Live Messaging]
  E --> F[Messaging thread in Salesforce]
  F --> G[Rep replies — lands in the widget]
```

## Setting up

<Steps>
  <Step title="Confirm the widget is live">
    Open the page where you embedded the widget and send a test message. You should see the AI respond. If the widget doesn't load, walk through [Install Widget](/widget/install-widget) first.
  </Step>

  <Step title="Confirm Live Messaging is connected">
    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), open **Salesforce → MIAW**. All six fields should be filled and saved. If not, complete the [Live Messaging setup](/integrations/salesforce/live-messaging).
  </Step>

  <Step title="Trigger a test handoff">
    Send a message like *"I want to talk to a human"* in the widget. The AI should hand off the conversation.
  </Step>

  <Step title="Verify in the Salesforce console">
    The conversation should appear as a **messaging thread** routed through Omni-Channel. Reply from Salesforce and confirm the message lands in the visitor's widget within a couple of seconds.
  </Step>
</Steps>

<Tip>
  If the conversation doesn't appear in Salesforce, check that your Omni-Channel flow is configured for the Embedded Service Deployment. See [Troubleshooting](/integrations/salesforce/troubleshooting#live-messaging).
</Tip>

## What the rep sees

* A **messaging thread in the Salesforce console** routed through Omni-Channel.
* The full AI-to-visitor transcript attached to the conversation.
* Routing attributes including `OpencxSessionId` — the trace key back to the OpenCX session.
* Replies typed in the Salesforce console land back in the visitor's widget within a couple of seconds.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Authenticated visitors vs anonymous visitors" icon="shield-check">
    When the widget passes a verified email via [widget authentication](/widget/authentication), OpenCX generates an authenticated identity token. Anonymous visitors get an unauthenticated token. Both flow through the same Embedded Service Deployment — your Omni-Channel flow can use the `Chat_Consumer_Type` routing attribute to route differently.
  </Accordion>

  <Accordion title="Files visitors upload" icon="paperclip">
    Files uploaded in the widget appear as attachments on the messaging thread in the Salesforce console. File-size limits follow your Salesforce org's messaging configuration.
  </Accordion>

  <Accordion title="Widget custom components still render on the visitor side" icon="bolt">
    When an AI action returns data rendered by a [custom component](/widget/custom-components), the visitor sees the richer UI. Your rep sees the underlying text in the Salesforce console — pick copy that reads well in both surfaces.
  </Accordion>

  <Accordion title="CSAT after the chat ends" icon="star">
    If your workflow triggers <Tooltip>CSAT</Tooltip>, the rating and comment land on the OpenCX session (visible in the [Inbox](https://platform.open.cx/inbox)), not in Salesforce.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Chat Widget" icon="messages" href="/widget/introduction">
    The channel itself — install, configure, authenticate.
  </Card>

  <Card title="Live Messaging setup" icon="plug" href="/integrations/salesforce/live-messaging">
    JWT credentials, routing attributes, and connection.
  </Card>

  <Card title="Salesforce overview" icon="cloud" href="/integrations/salesforce/overview">
    What Salesforce lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/salesforce/troubleshooting">
    Conversations not appearing, routing issues.
  </Card>
</CardGroup>


# Email Cases
Source: https://docs.open.cx/integrations/salesforce/email-cases

Connect Salesforce so email handoffs create Cases your reps work from the console they already use.

The Email Cases path wires OpenCX into Salesforce Case Management. Use it for **email** — the channel where every handoff should become a trackable <Tooltip>Case</Tooltip>. Chat, SMS, WhatsApp, and phone belong on [Live Messaging](/integrations/salesforce/live-messaging) instead.

<SalesforceEmailFlow />

<Info>
  Setup takes about 30 minutes. You need a Salesforce System Administrator profile and admin access in OpenCX.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Salesforce edition with API access" icon="circle-check">
    Enterprise, Unlimited, or Developer edition. Professional edition requires API access to be enabled separately.
  </Accordion>

  <Accordion title="System Administrator profile in Salesforce" icon="user-shield">
    You need to create a Connected App, a Named Credential, an Apex Class, and an Apex Trigger. Standard user roles cannot reach these.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="key">
    Required to save integration settings in [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Create an External Client App in Salesforce">
    <Note>
      Salesforce **Starter** edition does not support Connected Apps or External Client Apps. OAuth/API integrations require **Enterprise**, **Unlimited**, **Developer**, or **Performance** edition.
    </Note>

    **External Client Apps (ECAs) are Salesforce's current-generation connected apps and the recommended way to connect OpenCX.** A classic Connected App also works (see the note at the end of this step). One scope caveat decides everything: an ECA **cannot grant the `Full access (full)` scope**, so an ECA connection must use the least-privilege scope set below. OpenCX requests `full` by default for historical reasons — **before connecting with an ECA, ask OpenCX to switch your workspace to least-privilege scopes**, or the login ends in `OAUTH_APPROVAL_ERROR_GENERIC`.

    **Create the app** in the **same Salesforce org you will log into when connecting** — an ECA is local to its org, and authorizing into any other org fails with `OAUTH_AUTHORIZATION_BLOCKED: Cross-org OAuth flows are not supported for this external client app`.

    Go to **Setup → App Manager → New External Client App**:

    1. Fill in the basics (App Name, API Name, Contact Email) and set **Distribution State** to **Local**.
    2. Enable **OAuth Settings** and set the **Callback URL** to:
       ```
       https://api.open.cx/backend/salesforce-case-management/oauth/callback
       ```
    3. Select exactly these OAuth scopes:

       | Checkbox | Emits |
       | - | - |
       | **Manage user data via APIs** | `api` |
       | **Access the identity URL service** | `id` |
       | **Perform requests at any time** | `refresh_token`, `offline_access` |

       Do not add others, and do not pick `Full access` — the app cannot grant it.
    4. Under the app's **OAuth policies**, check **Require Secret for Web Server Flow** and **Require Secret for Refresh Token Flow**. PKCE is required by default on ECAs; OpenCX always sends it.
    5. Set the **Refresh Token Policy** to **Refresh token is valid until revoked**. Any expiring policy kills the integration silently when the timer lapses — the most common cause of "it worked yesterday".
    6. **Strongly recommended:** enable the **Client Credentials Flow** and set the integration user as its **Run As** user. This lets the connection be restored programmatically if the refresh token is ever revoked, without another interactive login.
    7. Save.

    <Note>
      **Why these three scopes are sufficient** — verified against a live org by exercising every operation the integration performs:

      | Scope | Why it's needed |
      | - | - |
      | **Manage user data via APIs** (`api`) | Every SOQL query and every create/update/delete on Case, EmailMessage, CaseComment, Contact, User, RecordType, OrgWideEmailAddress, ContentVersion, ContentDocumentLink and Attachment. |
      | **Access the identity URL service** (`id`) | Resolving the integration user, which the draft-reply and attachment paths use to find records they own. Without it those paths fail. |
      | **Perform requests at any time** (`refresh_token`, `offline_access`) | Refreshing the access token. Without it the integration stops working when the token expires and needs manual re-auth. |

      The integration is data-plane only — it makes no Metadata API, Tooling API or SOAP calls — which is why `api` covers it.

      Two consequences worth knowing:

      * **An OAuth scope never grants more than the integration user's own profile allows.** Even with `full`, the token can only reach what that user can reach. Provisioning a dedicated integration user with a minimal profile is the stronger lever, and it works no matter which scope you pick — see the object permissions below.
      * **The narrow set is what makes External Client Apps work.** ECAs cannot grant `full`; on these three scopes they connect and operate fully (verified in production on an ECA org).

      **Minimum object permissions for the integration user:**

      | Object | Permissions |
      | - | - |
      | Case | Read, Edit |
      | EmailMessage | Read, Create, Edit, Delete (delete is required to clear stale assist drafts) |
      | CaseComment | Read, Create |
      | ContentVersion, ContentDocumentLink | Read, Create, Delete |
      | Attachment | Read, Create |
      | Contact, User, RecordType, OrgWideEmailAddress | Read |
    </Note>

    <Note>
      **Classic Connected App alternative.** If your org standardizes on classic Connected Apps: newer orgs must first enable creation under **Setup → External Client Apps → External Client App Settings → Allow creation of connected apps**, then **App Manager → New Connected App** with the same callback URL, either the least-privilege scopes above or **Full access (full)** plus **Perform requests at any time**, both **Require Secret** checkboxes, and the same **valid until revoked** refresh token policy.
    </Note>

    **Copy the Consumer Key and Consumer Secret:**

    1. In **App Manager** (or **Setup → External Client Apps**), open your app.
    2. Under **API (Enable OAuth Settings)**, click **Manage Consumer Details**.
    3. Salesforce will ask you to verify your identity — typically an email verification code or other MFA challenge.
    4. After you verify, Salesforce opens a page displaying the **Consumer Key** and **Consumer Secret**. Copy both.

    <Warning>
      It may take 2–10 minutes for a new Connected App to activate — if the next step fails with `invalid_client_id`, wait and retry. And if you ever recreate the app, paste the **new** Consumer Key and Secret into OpenCX before reconnecting; the saved credentials are what get sent to Salesforce.
    </Warning>
  </Step>

  <Step title="Enter credentials and connect">
    <Frame>
      <video>
        <source type="video/mp4" />
      </video>
    </Frame>

    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), open **Salesforce** and choose **Case Management**.

    | Field | Value |
    | - | - |
    | **Consumer Key** | The Consumer Key from your Connected App. |
    | **Consumer Secret** | The Consumer Secret from your Connected App. |
    | **Login URL** | `https://login.salesforce.com` for production. Use `https://test.salesforce.com` for sandbox environments. |
    | **Redirect URI** | Auto-populated. Do not change this value. |

    Click **Save and Connect**. A Salesforce login window opens. Sign in, then on the authorization screen click **Allow** to grant OpenCX access. When you return to OpenCX, the status shows **Connected**.

    <Note>
      The **Webhook URL** appears only after the connection succeeds — it does not show up the moment you open the Case Management form. Complete the **Save and Connect → Allow** flow first, then the URL is revealed in the same place for you to copy in the next step.
    </Note>
  </Step>

  <Step title="Set up Email-to-Case routing and mail forwarding">
    OpenCX sends outbound emails from inside Salesforce (via the Apex trigger further down). For contacts to reach Salesforce in the first place — and for their replies to flow back onto the same Case — you need an Email-to-Case routing address configured and your customer-facing mailbox forwarding into it.

    **1. Enable Email-to-Case.** Go to **Setup → Quick Find → "Email-to-Case" → Email-to-Case Settings** and confirm:

    * **Enable Email-to-Case** — checked.
    * **Enable on-demand service** — checked (this is what makes the Salesforce-generated inbound address work without running a local agent).
    * **Insert email threading token in email subject** — checked.
    * **Insert email threading token in email body** — checked.
    * **Use email headers for threading** — checked.

    Once Email-to-Case is enabled, it can't be disabled, but its settings can be edited. If the feature is already enabled, just verify the checkboxes above.

    **2. Create a Routing Address.** On the same Email-to-Case Settings page, scroll to **Routing Addresses** and click **New**. Fill the form exactly as follows for a production-ready setup:

    **Routing Information**

    | Field | Value | Notes |
    | - | - | - |
    | **Routing Name** | `OpenCX Support` (or one label per support queue / region) | Display label only. Create one routing address per customer-facing mailbox. |
    | **Email Address** | `support@yourcompany.com` | The actual address customers email. Must be on a domain you control. Never use a personal inbox in production. |
    | **Controlled by Permission Set** | Unchecked | Only enable if you gate routing access via permission sets. |

    **Email Settings**

    | Field | Value | Notes |
    | - | - | - |
    | **Save Email Headers** | **Checked** | Required for reliable Lightning Threading — headers are how customer replies get matched back to the correct Case when quoted-body tokens aren't preserved. |
    | **Accept Email From** | Blank | Only populate for internal-only support (e.g. `@yourcompany.com` domain allowlist). A populated list silently discards mail from anyone not on it. |

    **Task Settings**

    | Field | Value | Notes |
    | - | - | - |
    | **Create Task from Email** | Unchecked | The `EmailMessage` record on the Case is the source of truth. Auto-creating a Task on top of it clutters reps' task lists. |
    | **Task Status** | — | Ignored when the checkbox above is off. If you do enable Task creation, use `Completed`. |

    **Case Settings**

    | Field | Value | Notes |
    | - | - | - |
    | **Case Owner** | A Queue (change the dropdown from `User` to `Queue`, e.g. `Tier 1 Support`) | A Queue gives the whole team visibility and lets Assignment Rules / Omni-Channel redistribute work. A single User bottlenecks every Case on that person. Leave blank only if Case Assignment Rules own initial ownership. |
    | **Case Priority** | `Medium` | Reasonable default. Override later via Assignment Rules or a Flow. |
    | **Case Origin** | `Email` | Must be set (required field). Matches what OpenCX writes and enables filtering on email-originated Cases. |

    **Flow Settings**

    | Field | Value | Notes |
    | - | - | - |
    | **Omni-Channel Flow** | Blank | Only populate if using Salesforce Omni-Channel. Most orgs starting out route via Assignment Rules instead. |
    | **Fallback Queue** | Blank | Only used as a backup if the Omni-Channel flow fails to route. |

    Save. Salesforce then emails a verification link to the **Email Address** you entered — open that inbox and click the link. The address must show **Verified** before anything will work.

    Salesforce also auto-generates a long **Email Services Address** at the bottom of the routing record — something like:

    ```
    support@ffbg6d2e0u5d287mxdvcji8a7ebeorhc26atdodxn5bzy3c95.gk-nowtbuar.can96.case.salesforce.com
    ```

    **Copy this long address.** You'll forward into it in the next step. To retrieve it later: **Setup → Email-to-Case → Routing Addresses → \[row] → Email Services Address**.

    **3. Forward your customer-facing mailbox to the Salesforce inbound address.** Email clients don't let you set Salesforce as an MX target directly (unless you control the DNS zone for the customer-facing domain). The reliable path is standard forwarding at the mailbox level. Example for Gmail:

    1. In Gmail for `support@yourcompany.com`, open **Settings → Forwarding and POP/IMAP → Add a forwarding address**.
    2. Paste the long `...case.salesforce.com` address.
    3. Gmail sends a verification email to that address. Because the destination is Salesforce, the verification email lands as a new Case in your org. In Developer Console → Query Editor:

       ```sql theme={"dark"}
       SELECT Id, Subject, TextBody, CreatedDate
       FROM EmailMessage
       WHERE FromAddress = 'forwarding-noreply@google.com'
       ORDER BY CreatedDate DESC
       LIMIT 1
       ```

       Open the newest row and copy the 9-digit code from `TextBody`.
    4. Paste the code back into Gmail's forwarding screen → **Verify**. The address should now be **Confirmed** and forwarding is live.

    Other providers (Outlook, FastMail, custom domains on cPanel, etc.) follow the same shape — forward → verify via the code Salesforce captured. If forwarding stays stuck at "Unverified", no Cases will be created; don't proceed until it's Verified.

    <Note>
      Plain mailbox forwarding can fail anti-spam / DMARC checks on the way into Salesforce. If test emails never turn into Cases after the forward is verified, publish `include:_spf.salesforce.com` in your SPF record, or use SRS-aware forwarding.
    </Note>
  </Step>

  <Step title="Configure the webhook in Salesforce">
    After connecting, OpenCX displays a **Webhook URL**. It looks like this, with the token as the final path segment:

    ```
    https://api.open.cx/backend/salesforce-case/webhook/eyJhbGciOi…
    └──────────── base URL ────────────────────────┘ └── token ──┘
    ```

    Split it into two parts — you need them separately below:

    * **Base URL** — everything up to and including `/webhook`
    * **Token** — the final path segment

    <Warning>
      The token is a credential. Treat it like a password: keep it out of the callout URL, out of Apex source, and out of anything you paste into a ticket or a screenshot.
    </Warning>

    <Note>
      **Send the token as a header, not in the URL.** The endpoint accepts it three ways, in this order of precedence:

      1. `x-opencx-token: <token>` — recommended
      2. `Authorization: Bearer <token>`
      3. the final path segment of the URL — **legacy**, still accepted so existing setups keep working

      Prefer a header. A token in the URL path leaks into Salesforce debug logs, Apex Jobs entries, and anywhere the callout URL is copied.
    </Note>

    **Create a Named Credential** in Salesforce:

    1. Go to **Setup → Security → Named Credentials**. On the Named Credentials page, click the **dropdown arrow next to New** and choose **New Legacy**.
    2. Set **Label** to `OpenCX_Integration`. The **Name** field auto-populates from the label — it must end up exactly `OpenCX_Integration`, because the Apex class below references it as `callout:OpenCX_Integration`. If you pick a different Name, update every `callout:` reference in the Apex class to match — otherwise every webhook callout fails silently (visible only as failed jobs in **Setup → Apex Jobs**) and no sessions are created in OpenCX.
    3. Paste the **base URL** into the **URL** field — *without* the token segment.
    4. Under **Authentication**, set **Identity Type** to `Anonymous` and **Authentication Protocol** to `No Authentication`.
    5. Under **Callout Options**, check **Generate Authorization Header** and **Allow Merge Fields in HTTP Body**.
    6. Save.

    **Store the token so Apex can read it without hardcoding it.** Legacy Named Credentials have no custom-header field, so the header is set in Apex — but the value should not live in the class body. Create a protected Custom Setting to hold it:

    1. Go to **Setup → Custom Settings → New**.
    2. **Label** `OpenCX Settings`, **Object Name** `OpenCX_Settings`, **Setting Type** `Hierarchy`, **Visibility** `Protected`.
    3. Save, then **New** in the Custom Fields section: a **Text(255)** field named `Webhook_Token`.
    4. Click **Manage → New** at the org-default level and paste the token into `Webhook_Token`. Save.

    A protected hierarchy Custom Setting is not readable from outside the org's namespace and does not appear in the callout URL, so the token stays out of debug logs and out of source control.

    <Tip>
      If your org uses the newer **External Credential** model instead of legacy Named Credentials, you can attach a **Custom Header** (`x-opencx-token`) directly to the credential and skip the Custom Setting — Salesforce then stores and injects the token itself, and the Apex below no longer needs the `setHeader` line.
    </Tip>

    **Create the Apex Class:**

    <Note>
      Every class and trigger name in the rest of this step is an **example** — you may keep the suggested names or pick your own. Names don't affect behavior, but if you rename the Apex class, update every trigger's reference to match.
    </Note>

    Go to **Setup → Apex Classes** and click **New**. Alternatively, open the **Developer Console** (top-right gear icon → **Developer Console**), then go to **File → New → Apex Class**. Either path works.

    Paste the following (the class name `OpenSalesforceCaseManagement` is an example — rename freely, but remember to update the triggers below to match):

    ```apex theme={"dark"}
    public class OpenSalesforceCaseManagement {
        @future(callout=true)
        public static void sendCaseEvents(List<Id> caseIds) {
            Http http = new Http();

            for (Id caseId : caseIds) {
                try {
                    String endpointUrl = 'callout:OpenCX_Integration?caseId=' + EncodingUtil.urlEncode(caseId, 'UTF-8');

                    HttpRequest req = new HttpRequest();
                    req.setEndpoint(endpointUrl);
                    req.setMethod('POST');
                    req.setHeader('Content-Type', 'application/json');
                    req.setHeader('x-opencx-token', OpenCX_Settings__c.getOrgDefaults().Webhook_Token__c);
                    req.setBody('');

                    HttpResponse res = http.send(req);
                    System.debug('Sent webhook for Case ' + caseId + ', response: ' + res.getBody());
                } catch (Exception e) {
                    System.debug('Failed to send webhook for Case ' + caseId + ': ' + e.getMessage());
                }
            }
        }

        @future(callout=true)
        public static void sendCaseReplyEvents(List<Id> caseIds) {
            Http http = new Http();
            for (Id caseId : caseIds) {
                try {
                    String endpointUrl = 'callout:OpenCX_Integration?caseId=' + EncodingUtil.urlEncode(caseId, 'UTF-8') + '&type=new_user_reply';

                    HttpRequest req = new HttpRequest();
                    req.setEndpoint(endpointUrl);
                    req.setMethod('POST');
                    req.setHeader('Content-Type', 'application/json');
                    req.setHeader('x-opencx-token', OpenCX_Settings__c.getOrgDefaults().Webhook_Token__c);
                    req.setBody('');

                    HttpResponse res = http.send(req);
                    System.debug('Sent webhook for Case ' + caseId + ', response: ' + res.getBody());
                } catch (Exception e) {
                    System.debug('Failed to send webhook for Case ' + caseId + ': ' + e.getMessage());
                }
            }
        }

        public static void sendCaseEmailFromHumanAgentEvents(List<Id> caseIds) {
            sendCaseEmailFromHumanAgentEventsWithIds(caseIds, new List<Id>());
        }

        // emailIds[i] (optional, parallel to caseIds) is the sent EmailMessage Id —
        // passed as commentId so OpenCX mirrors the actual email body. Used by the
        // draft-sent branch of OpenCxHumanAgentReplyTrigger.
        @future(callout=true)
        public static void sendCaseEmailFromHumanAgentEventsWithIds(List<Id> caseIds, List<Id> emailIds) {
            Http http = new Http();
            for (Integer i = 0; i < caseIds.size(); i++) {
                Id caseId = caseIds[i];
                try {
                    String endpointUrl = 'callout:OpenCX_Integration?caseId=' + EncodingUtil.urlEncode(caseId, 'UTF-8') + '&type=new_human_agent_reply';
                    if (i < emailIds.size() && emailIds[i] != null) {
                        endpointUrl += '&commentId=' + EncodingUtil.urlEncode(emailIds[i], 'UTF-8');
                    }

                    HttpRequest req = new HttpRequest();
                    req.setEndpoint(endpointUrl);
                    req.setMethod('POST');
                    req.setHeader('Content-Type', 'application/json');
                    req.setHeader('x-opencx-token', OpenCX_Settings__c.getOrgDefaults().Webhook_Token__c);
                    req.setBody('');

                    HttpResponse res = http.send(req);
                    System.debug('Sent webhook for Case Human Agent Email ' + caseId + ', response: ' + res.getBody());
                } catch (Exception e) {
                    System.debug('Failed to send webhook for Case Human Agent Email ' + caseId + ': ' + e.getMessage());
                }
            }
        }

        @future(callout=true)
        public static void sendCaseOwnerChangedEvents(List<Id> caseIds) {
            Http http = new Http();
            for (Id caseId : caseIds) {
                try {
                    String endpointUrl = 'callout:OpenCX_Integration?caseId=' + EncodingUtil.urlEncode(caseId, 'UTF-8') + '&type=owner_changed';

                    HttpRequest req = new HttpRequest();
                    req.setEndpoint(endpointUrl);
                    req.setMethod('POST');
                    req.setHeader('Content-Type', 'application/json');
                    req.setHeader('x-opencx-token', OpenCX_Settings__c.getOrgDefaults().Webhook_Token__c);
                    req.setBody('');

                    HttpResponse res = http.send(req);
                    System.debug('Sent webhook for Case Owner change ' + caseId + ', response: ' + res.getBody());
                } catch (Exception e) {
                    System.debug('Failed to send webhook for Case Owner change ' + caseId + ': ' + e.getMessage());
                }
            }
        }

        @future(callout=true)
        public static void sendCaseClosedEvents(List<Id> caseIds) {
            Http http = new Http();
            for (Id caseId : caseIds) {
                try {
                    String endpointUrl = 'callout:OpenCX_Integration?caseId=' + EncodingUtil.urlEncode(caseId, 'UTF-8') + '&type=case_closed';

                    HttpRequest req = new HttpRequest();
                    req.setEndpoint(endpointUrl);
                    req.setMethod('POST');
                    req.setHeader('Content-Type', 'application/json');
                    req.setHeader('x-opencx-token', OpenCX_Settings__c.getOrgDefaults().Webhook_Token__c);
                    req.setBody('');

                    HttpResponse res = http.send(req);
                    System.debug('Sent webhook for Case close ' + caseId + ', response: ' + res.getBody());
                } catch (Exception e) {
                    System.debug('Failed to send webhook for Case close ' + caseId + ': ' + e.getMessage());
                }
            }
        }

    }
    ```

    **Save the class:** click **Save** at the bottom of the Salesforce UI, or in the Developer Console use **File → Save** (⌘S on Mac, Ctrl+S on Windows/Linux).

    **Create the Apex Triggers:**

    OpenCX needs six triggers in total: three core triggers for new cases, customer email replies, and human-agent emails sent from the Case; two optional triggers for owner reassignment and case close; and one required trigger that actually transmits outbound AI replies to the contact.

    All six triggers are authored the same way. To open the trigger editor:

    1. In Salesforce, open the **Developer Console** (top-right gear icon → **Developer Console**).
    2. From the Developer Console's top-left menu, go to **File → New → Apex Trigger**.
    3. Fill in the **Name** (examples below — rename to whatever you prefer) and the **sObject**, then click **Submit**.
    4. Paste the snippet into the editor.
    5. Save with **File → Save** (or ⌘S on Mac, Ctrl+S on Windows/Linux).

    **1. Case trigger (new cases)** — Name: `CaseTrigger` (example, renameable — the Name must match the name declared in the trigger code). sObject: `Case`.

    ```apex theme={"dark"}
    trigger CaseTrigger on Case (after insert) {
        List<Id> caseIds = new List<Id>();
        for (Case c : Trigger.new) {
            caseIds.add(c.Id);
        }
        OpenSalesforceCaseManagement.sendCaseEvents(caseIds);
    }
    ```

    **2. EmailMessage trigger (customer replies)** — Name: `OpenCxCustomerReplyTrigger` (example, renameable). sObject: `EmailMessage`.

    ```apex theme={"dark"}
    trigger OpenCxCustomerReplyTrigger on EmailMessage (after insert) {
        List<Id> caseIds = new List<Id>();
        for (EmailMessage em : Trigger.new) {
            // Customer reply = Incoming, attached to a Case (Ids starting with 500).
            if (em.Incoming == true
                && em.ParentId != null
                && String.valueOf(em.ParentId).startsWith('500')) {
                caseIds.add(em.ParentId);
            }
        }
        if (!caseIds.isEmpty()) {
            OpenSalesforceCaseManagement.sendCaseReplyEvents(caseIds);
        }
    }
    ```

    Without this trigger, OpenCX won't see customer replies and the AI can't follow up. Outbound emails (ones OpenCX sends via API) have `Incoming=false` and are skipped, so no self-loop.

    **3. EmailMessage trigger (human agent sends email from Salesforce)** — optional but recommended. Name: `OpenCxHumanAgentReplyTrigger` (example, renameable). sObject: `EmailMessage`.

    <Warning>
      Set `INTEGRATION_USERNAME` (first line of the trigger) to the exact **Username** of the user OpenCX authenticated as during OAuth. In `after insert`, `UserInfo.getUserId()` always equals `CreatedById`, so comparing the two would never discriminate between OpenCX and a human agent. We must compare against the integration user's actual Id, resolved via their Username.
    </Warning>

    ```apex theme={"dark"}
    trigger OpenCxHumanAgentReplyTrigger on EmailMessage (after insert, after update) {
        // REQUIRED: the exact Username of the user OpenCX OAuth'd as.
        final String INTEGRATION_USERNAME = 'opencx-integration@yourcompany.com';

        List<User> matches = [SELECT Id FROM User WHERE Username = :INTEGRATION_USERNAME LIMIT 1];
        if (matches.isEmpty()) return;
        Id integrationUserId = matches[0].Id;

        List<Id> caseIds = new List<Id>();
        List<Id> emailIds = new List<Id>();
        for (EmailMessage em : Trigger.new) {
            if (em.ParentId == null || em.ParentId.getSObjectType() != Case.SObjectType) continue;
            if (Trigger.isInsert) {
                // Outbound email on a Case from anyone OTHER than OpenCX — i.e.
                // a human agent using Salesforce's Send Email UI. Skip drafts
                // (Status '5'): saving a draft is not a reply — the update
                // branch below fires when it is actually sent.
                if (em.Incoming == false && em.Status != '5' && em.CreatedById != integrationUserId) {
                    caseIds.add(em.ParentId);
                    emailIds.add(em.Id);
                }
            } else {
                // Draft → sent transition. Assist-mode drafts are CREATED by the
                // integration user, so a human sending one is an UPDATE of that
                // row (Status leaves '5') — the insert branch never sees it.
                EmailMessage oldEm = Trigger.oldMap.get(em.Id);
                if (oldEm.Status == '5' && em.Status != '5' && em.Incoming == false) {
                    caseIds.add(em.ParentId);
                    emailIds.add(em.Id);
                }
            }
        }
        if (!caseIds.isEmpty()) {
            OpenSalesforceCaseManagement.sendCaseEmailFromHumanAgentEventsWithIds(caseIds, emailIds);
        }
    }
    ```

    Use this if your agents sometimes reply directly in Salesforce via the Case's **Send Email** action — OpenCX will mark the session as handed off and log the agent's reply in the chat history. The `after update` branch covers agents sending an OpenCX-suggested **draft** (assist mode's "post suggested replies as email drafts" toggle): sending a draft updates the existing EmailMessage rather than inserting a new one.

    **4. Case trigger (owner change)** — optional but recommended. When a rep manually reassigns the Case (taking ownership away from the OpenCX integration user), the AI should stop replying. Name: `OpenCxOwnerChangeTrigger` (example, renameable). sObject: `Case`.

    <Note>
      Set `INTEGRATION_USERNAME` (second line of the trigger) to the exact **Username** OpenCX authenticated as during OAuth — the same value used by triggers 3, 6 and 7. OpenCX's own owner writes (takeover, assignee sync) run as that user and are skipped here. Leaving it wrong is safe but noisier: OpenCX's write echoes back and OpenCX de-duplicates it.
    </Note>

    ```apex theme={"dark"}
    trigger OpenCxOwnerChangeTrigger on Case (after update) {
        // REQUIRED: the exact Username OpenCX OAuth'd as — same value as triggers 3, 6, 7.
        String INTEGRATION_USERNAME = 'opencx-integration@yourcompany.com';
        if (UserInfo.getUserName() == INTEGRATION_USERNAME) return;

        List<Id> caseIds = new List<Id>();
        for (Case c : Trigger.new) {
            Case old = Trigger.oldMap.get(c.Id);
            if (old == null) continue;
            if (c.OwnerId != old.OwnerId) {
                caseIds.add(c.Id);
            }
        }
        if (!caseIds.isEmpty()) {
            OpenSalesforceCaseManagement.sendCaseOwnerChangedEvents(caseIds);
        }
    }
    ```

    When this fires, OpenCX marks the session as handed-off and pauses autonomous AI replies. OpenCX's own ownership changes (during takeover / handoff) skip via the `INTEGRATION_USERNAME` check; a rep accepting or taking the Case fires normally.

    **5. Case trigger (case closed)** — optional but recommended. When a rep closes the Case in Salesforce, OpenCX resolves the matching session. Name: `OpenCxCaseClosedTrigger` (example, renameable). sObject: `Case`.

    ```apex theme={"dark"}
    trigger OpenCxCaseClosedTrigger on Case (after update) {
        List<Id> caseIds = new List<Id>();
        for (Case c : Trigger.new) {
            Case old = Trigger.oldMap.get(c.Id);
            if (old == null) continue;
            if (c.IsClosed && !old.IsClosed) {
                caseIds.add(c.Id);
            }
        }
        if (!caseIds.isEmpty()) {
            OpenSalesforceCaseManagement.sendCaseClosedEvents(caseIds);
        }
    }
    ```

    Without this trigger, sessions stay open in OpenCX after their Case is closed in Salesforce.

    **6. EmailMessage trigger (outbound email delivery)** — **required**. This is the trigger that actually transmits OpenCX's AI replies to the contact, injects Salesforce's threading token so customer replies attach to the same Case, and redirects replies back to your Email-to-Case routing address. Name: `OpenCxOutboundEmailSender` (example, renameable). sObject: `EmailMessage`.

    <Warning>
      Before saving, set both constants at the top of the trigger:

      * `INTEGRATION_USERNAME` — the exact **Username** of the user OpenCX OAuth'd as. Find it in **Setup → Users → Users** (the `Username` column, looks like an email). This must match exactly or the trigger silently skips every outbound EmailMessage.
      * `REPLY_TO_ADDRESS` — your customer-facing forwarding address, e.g. `support@yourcompany.com`. Must be registered as a **Verified** Routing Address in **Setup → Email-to-Case → Routing Addresses**.
    </Warning>

    ```apex theme={"dark"}
    trigger OpenCxOutboundEmailSender on EmailMessage (after insert) {
        // ==== CONFIGURE THESE TWO VALUES ====
        final String INTEGRATION_USERNAME = 'opencx-integration@yourcompany.com';
        final String REPLY_TO_ADDRESS     = 'support@yourcompany.com';
        // ====================================

        List<User> userMatches = [SELECT Id FROM User WHERE Username = :INTEGRATION_USERNAME LIMIT 1];
        if (userMatches.isEmpty()) {
            System.debug(LoggingLevel.ERROR,
                'OpenCxOutboundEmailSender: integration user not found: ' + INTEGRATION_USERNAME);
            return;
        }
        Id integrationUserId = userMatches[0].Id;

        // Step 1 — filter to OpenCX's own outbound EmailMessages on a Case with a recipient.
        List<EmailMessage> toSend = new List<EmailMessage>();
        Set<Id> emIds = new Set<Id>();
        Set<Id> caseIds = new Set<Id>();
        for (EmailMessage em : Trigger.new) {
            if (em.Incoming != false) continue;
            if (em.ParentId == null) continue;
            if (em.ParentId.getSObjectType() != Case.SObjectType) continue;
            if (em.CreatedById != integrationUserId) continue;
            if (em.Status == '5') continue; // draft — never auto-send (assist-mode draft replies)
            if (String.isBlank(em.ToAddress)) continue;
            toSend.add(em);
            emIds.add(em.Id);
            caseIds.add(em.ParentId);
        }
        if (toSend.isEmpty()) return;

        // Step 2a — find the most recent prior EmailMessage on each Case so we
        // can set In-Reply-To / References headers for client-side threading.
        Map<Id, String> prevMsgIdByCase = new Map<Id, String>();
        for (EmailMessage prev : [
            SELECT ParentId, MessageIdentifier, MessageDate
            FROM EmailMessage
            WHERE ParentId IN :caseIds
              AND Id NOT IN :emIds
              AND MessageIdentifier != null
            ORDER BY MessageDate DESC
        ]) {
            if (!prevMsgIdByCase.containsKey(prev.ParentId)) {
                prevMsgIdByCase.put(prev.ParentId, prev.MessageIdentifier);
            }
        }

        // Step 2b — bulk-load any attachments on these EmailMessages so we can
        // forward them. Supports modern files (ContentDocumentLink) only.
        Map<Id, List<Messaging.EmailFileAttachment>> attachmentsByEm =
            new Map<Id, List<Messaging.EmailFileAttachment>>();
        List<ContentDocumentLink> links = [
            SELECT LinkedEntityId, ContentDocumentId
            FROM ContentDocumentLink
            WHERE LinkedEntityId IN :emIds
        ];
        if (!links.isEmpty()) {
            Set<Id> docIds = new Set<Id>();
            for (ContentDocumentLink l : links) docIds.add(l.ContentDocumentId);
            Map<Id, ContentVersion> versionByDoc = new Map<Id, ContentVersion>();
            for (ContentVersion cv : [
                SELECT Id, ContentDocumentId, Title, FileExtension, VersionData
                FROM ContentVersion
                WHERE ContentDocumentId IN :docIds AND IsLatest = true
            ]) {
                versionByDoc.put(cv.ContentDocumentId, cv);
            }
            for (ContentDocumentLink l : links) {
                ContentVersion cv = versionByDoc.get(l.ContentDocumentId);
                if (cv == null) continue;
                String name = (cv.Title != null ? cv.Title : 'attachment');
                if (!String.isBlank(cv.FileExtension)) name += '.' + cv.FileExtension;
                Messaging.EmailFileAttachment att = new Messaging.EmailFileAttachment();
                att.setFileName(name);
                att.setBody(cv.VersionData);
                List<Messaging.EmailFileAttachment> attList = attachmentsByEm.get(l.LinkedEntityId);
                if (attList == null) {
                    attList = new List<Messaging.EmailFileAttachment>();
                    attachmentsByEm.put(l.LinkedEntityId, attList);
                }
                attList.add(att);
            }
        }

        // Step 3 — build each SingleEmailMessage.
        List<Messaging.SingleEmailMessage> emails = new List<Messaging.SingleEmailMessage>();
        for (EmailMessage em : toSend) {
            // Split ToAddress (required) / CcAddress / BccAddress on ',' or ';'.
            List<String> toAddresses = new List<String>();
            for (String raw : em.ToAddress.split('[,;]')) {
                String a = raw == null ? null : raw.trim();
                if (!String.isBlank(a)) toAddresses.add(a);
            }
            if (toAddresses.isEmpty()) continue;

            List<String> ccAddresses = new List<String>();
            if (!String.isBlank(em.CcAddress)) {
                for (String raw : em.CcAddress.split('[,;]')) {
                    String a = raw == null ? null : raw.trim();
                    if (!String.isBlank(a)) ccAddresses.add(a);
                }
            }

            List<String> bccAddresses = new List<String>();
            if (!String.isBlank(em.BccAddress)) {
                for (String raw : em.BccAddress.split('[,;]')) {
                    String a = raw == null ? null : raw.trim();
                    if (!String.isBlank(a)) bccAddresses.add(a);
                }
            }

            // Lightning-Threading token — rendered as 1px white-on-white so it
            // is invisible in the inbox, BUT without display:none / visibility
            // hidden, which Gmail and Outlook strip from quoted replies. This
            // styling survives the quote and lands back in Salesforce, which
            // matches it against the Case via Email-to-Case threading.
            String threadToken = EmailMessages.getFormattedThreadingToken(em.ParentId);
            String htmlBody = (em.HtmlBody != null ? em.HtmlBody : '')
                + '<span style="color:#ffffff;font-size:1px;line-height:0">'
                + threadToken + '</span>';

            Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
            mail.setToAddresses(toAddresses);
            if (!ccAddresses.isEmpty())  mail.setCcAddresses(ccAddresses);
            if (!bccAddresses.isEmpty()) mail.setBccAddresses(bccAddresses);
            mail.setReplyTo(REPLY_TO_ADDRESS);
            mail.setSubject(em.Subject);
            mail.setHtmlBody(htmlBody);
            if (!String.isBlank(em.TextBody)) mail.setPlainTextBody(em.TextBody);
            mail.setWhatId(em.ParentId);
            mail.setSaveAsActivity(false);

            // Header-based threading — when the customer hits Reply, their
            // client includes In-Reply-To / References pointing at this
            // message. Salesforce's "Use email headers for threading" setting
            // (enabled in E2C Settings) matches those to the Case. Normalise
            // the stored Message-ID to <...> wrapping; an unwrapped value
            // would be silently rejected.
            String prevMsgId = prevMsgIdByCase.get(em.ParentId);
            if (String.isNotBlank(prevMsgId)) {
                String stripped = prevMsgId.trim().removeStart('<').removeEnd('>').trim();
                if (String.isNotBlank(stripped)) {
                    String bracketed = '<' + stripped + '>';
                    mail.setInReplyTo(bracketed);
                    mail.setReferences(bracketed);
                }
            }

            List<Messaging.EmailFileAttachment> atts = attachmentsByEm.get(em.Id);
            if (atts != null && !atts.isEmpty()) mail.setFileAttachments(atts);

            emails.add(mail);
        }

        if (!emails.isEmpty()) {
            List<Messaging.SendEmailResult> results = Messaging.sendEmail(emails, false);
            for (Messaging.SendEmailResult r : results) {
                if (r.isSuccess()) continue;
                for (Messaging.SendEmailError err : r.getErrors()) {
                    System.debug(LoggingLevel.ERROR,
                        'OpenCxOutboundEmailSender sendEmail failed: '
                        + err.getStatusCode() + ' — ' + err.getMessage());
                }
            }
        }
    }
    ```

    <Warning>
      Without this trigger, OpenCX's AI replies are logged to the Case Feed as `EmailMessage` records but **never actually delivered** to the contact — a plain `EmailMessage` insert is a data row, not an SMTP send. The reply will show as "sent" in the OpenCX dashboard and appear in the Salesforce Case Feed, but the contact's inbox will stay empty.
    </Warning>

    **What each block does:**

    * `em.ParentId.getSObjectType() == Case.SObjectType` — matches `EmailMessage` rows whose parent is a Case, without hard-coding the `500` Id prefix.
    * `em.CreatedById != integrationUserId` / `==` — the reason we look up the integration user by Username instead of `UserInfo.getUserId()`. In `after insert`, `UserInfo.getUserId()` always equals `CreatedById`, so a naive equality check would always be true and the trigger would fire for every outbound EmailMessage — including human-agent sends, causing double-delivery.
    * `ContentDocumentLink` / `ContentVersion` query — forwards any files OpenCX attached to the outbound `EmailMessage` (modern Salesforce Files). If OpenCX never attaches files in your configuration, this runs once per trigger with zero rows and is effectively free.
    * `CcAddress` / `BccAddress` splitting — preserves cc / bcc recipients if OpenCX ever populates them. Split tolerates commas, semicolons, trailing whitespace, and empty segments.
    * `EmailMessages.getFormattedThreadingToken(em.ParentId)` — generates Salesforce's Lightning-Threading token. Embedded in a **visually hidden HTML `<span>`** so it never renders visibly, but still survives quoted replies from HTML-capable email clients. Text-only clients fall back to "Use email headers for threading".
    * `mail.setReplyTo(REPLY_TO_ADDRESS)` — routes customer replies back to your forwarding/routing address so Salesforce can ingest them. Without this, replies land in the integration user's personal Salesforce inbox and never reach Email-to-Case.
    * `mail.setSaveAsActivity(false)` — OpenCX already wrote the `EmailMessage` record that triggered this send; we don't want Salesforce to create a second one.
    * The `SendEmailResult` loop — logs `OpenCxOutboundEmailSender sendEmail failed:` to the Debug Log when a send is rejected (daily limit exceeded, deliverability off, malformed recipient, etc.). Surface these in **Setup → Debug Logs** when diagnosing delivery issues.

    **Org-Wide Email Address (recommended for production):** by default the email is sent from the integration user's personal Salesforce address. To send from a branded address like `support@yourcompany.com`, create an Organization-Wide Email Address in **Setup → Email → Organization-Wide Addresses**, verify it, then add this one line before `emails.add(mail)`:

    ```apex theme={"dark"}
    mail.setOrgWideEmailAddressId('0D2XXXXXXXXXXXX');  // Id of the verified OWA
    ```

    <Warning>
      **Upgrading from the retired `OpenCxCaseUpdatedTrigger`?** Earlier versions
      of this guide listed an optional 7th trigger — an `after update` on Case
      posting `?type=case_updated` on every save — to keep session attributes
      fresh. OpenCX now does that itself: it checks Salesforce every two minutes
      for Cases that changed and refreshes them in bulk, with nothing installed
      in your org.

      If you deployed that trigger, **delete it**, along with the
      `sendCaseUpdatedEvents` method on `OpenSalesforceCaseManagement` and its
      test method. Left in place it keeps firing one `@future` execution and one
      callout per Case save — against your org's async-Apex allocation and your
      webhook rate limit — for an event OpenCX now rejects. Nothing else changes;
      triggers 1–6 stay exactly as they are.
    </Warning>
  </Step>

  <Step title="Confirm email deliverability settings">
    Before the outbound email trigger can actually transmit, your Salesforce org needs two one-time settings:

    1. **Setup → Email → Deliverability → Access level** must be `All email`. The trial / sandbox default of `System email only` blocks `Messaging.sendEmail()` with `NO_MASS_MAIL_PERMISSION`.
    2. The integration user's profile must have **Send Email** enabled (standard on **System Administrator**).

    Skip this step at your own risk — the trigger will silently throw on every AI reply and nothing will leave Salesforce.
  </Step>

  <Step title="Create the Apex Test Class">
    Salesforce requires **≥ 75% test coverage** on every Apex class and trigger before you can deploy to production. This test class covers all five methods of `OpenSalesforceCaseManagement` plus all six triggers (new case, customer reply, human-agent reply, owner change, case close, outbound email delivery).

    Go to **Setup → Apex Classes** and click **New**, or open the **Developer Console** and go to **File → New → Apex Class**. The class name `OpenSalesforceCaseManagementTest` below is an example — you can rename it freely. Paste:

    ```apex theme={"dark"}
    @isTest
    private class OpenSalesforceCaseManagementTest {
        /**
         * Mocks every OpenCX webhook callout with a generic 200 response so
         * tests don't hit the real backend and don't depend on Named Credentials.
         */
        private class OpenCxCalloutMock implements HttpCalloutMock {
            public HttpResponse respond(HttpRequest req) {
                HttpResponse res = new HttpResponse();
                res.setStatusCode(200);
                res.setHeader('Content-Type', 'application/json');
                res.setBody('{"success":true}');
                return res;
            }
        }

        @isTest
        static void sendCaseEvents_sendsWebhook() {
            Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
            insert c;

            Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
            Test.startTest();
            OpenSalesforceCaseManagement.sendCaseEvents(new List<Id>{ c.Id });
            Test.stopTest();
        }

        @isTest
        static void sendCaseReplyEvents_sendsWebhook() {
            Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
            insert c;

            Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
            Test.startTest();
            OpenSalesforceCaseManagement.sendCaseReplyEvents(new List<Id>{ c.Id });
            Test.stopTest();
        }

        @isTest
        static void sendCaseEmailFromHumanAgentEvents_sendsWebhook() {
            Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
            insert c;

            Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
            Test.startTest();
            OpenSalesforceCaseManagement.sendCaseEmailFromHumanAgentEvents(new List<Id>{ c.Id });
            Test.stopTest();
        }

        @isTest
        static void sendCaseOwnerChangedEvents_sendsWebhook() {
            Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
            insert c;

            Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
            Test.startTest();
            OpenSalesforceCaseManagement.sendCaseOwnerChangedEvents(new List<Id>{ c.Id });
            Test.stopTest();
        }

        @isTest
        static void sendCaseClosedEvents_sendsWebhook() {
            Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
            insert c;

            Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
            Test.startTest();
            OpenSalesforceCaseManagement.sendCaseClosedEvents(new List<Id>{ c.Id });
            Test.stopTest();
        }


        @isTest
        static void caseTrigger_firesOnInsert() {
            Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
            Test.startTest();
            insert new Case(Subject = 'From trigger', Status = 'New', Origin = 'Email');
            Test.stopTest();
        }

        @isTest
        static void customerReplyTrigger_firesOnIncomingEmail() {
            Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
            insert c;

            Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
            Test.startTest();
            insert new EmailMessage(
                ParentId = c.Id,
                Incoming = true,
                Subject = 'Customer reply',
                TextBody = 'Hello',
                Status = '0'  // New
            );
            Test.stopTest();
        }

        @isTest
        static void humanAgentReplyTrigger_firesOnOutgoingEmail() {
            // Must match INTEGRATION_USERNAME in OpenCxHumanAgentReplyTrigger.
            // If that user doesn't exist in the test org, the trigger early-returns
            // and this test passes without exercising the full body.
            final String INTEGRATION_USERNAME = 'opencx-integration@yourcompany.com';
            List<User> integrationUsers = [
                SELECT Id FROM User WHERE Username = :INTEGRATION_USERNAME LIMIT 1
            ];
            if (integrationUsers.isEmpty()) return;

            // Run as a NON-integration user so the `CreatedById != integrationUserId`
            // guard treats the insert as a human-agent action.
            User runner = [
                SELECT Id FROM User
                WHERE IsActive = true AND Id != :integrationUsers[0].Id
                LIMIT 1
            ];
            Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
            insert c;

            Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
            Test.startTest();
            System.runAs(runner) {
                insert new EmailMessage(
                    ParentId = c.Id,
                    Incoming = false,
                    Subject = 'Agent reply',
                    TextBody = 'Hi there',
                    Status = '3'  // Sent
                );
            }
            Test.stopTest();
        }

        @isTest
        static void ownerChangeTrigger_firesOnOwnerUpdate() {
            Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
            insert c;

            List<User> candidates = [
                SELECT Id FROM User
                WHERE IsActive = true AND Id != :UserInfo.getUserId()
                LIMIT 1
            ];
            if (candidates.isEmpty()) return;

            Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
            Test.startTest();
            c.OwnerId = candidates[0].Id;
            update c;
            Test.stopTest();
        }

        @isTest
        static void caseClosedTrigger_firesOnClose() {
            Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
            insert c;

            Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
            Test.startTest();
            c.Status = 'Closed';
            update c;
            Test.stopTest();
        }


        @isTest
        static void outboundEmailSender_queuesEmail() {
            // Must match INTEGRATION_USERNAME in OpenCxOutboundEmailSender. If that
            // user doesn't exist in the test org, the trigger early-returns and
            // this test passes without exercising the full body.
            final String INTEGRATION_USERNAME = 'opencx-integration@yourcompany.com';
            List<User> integrationUsers = [
                SELECT Id FROM User WHERE Username = :INTEGRATION_USERNAME LIMIT 1
            ];
            if (integrationUsers.isEmpty()) return;
            User integrationUser = integrationUsers[0];

            Case c = new Case(Subject = 'Test', Status = 'New', Origin = 'Email');
            insert c;

            Test.setMock(HttpCalloutMock.class, new OpenCxCalloutMock());
            Test.startTest();
            // Run the EmailMessage insert AS the integration user so CreatedById
            // matches integrationUserId inside the trigger.
            System.runAs(integrationUser) {
                insert new EmailMessage(
                    ParentId  = c.Id,
                    Incoming  = false,
                    Subject   = 'AI reply',
                    TextBody  = 'Hi there',
                    HtmlBody  = '<p>Hi there</p>',
                    ToAddress = 'customer@example.com',
                    Status    = '3'  // Sent
                );
            }
            // Assert BEFORE stopTest — Test.stopTest() restores governor counters
            // to their pre-startTest state, so Limits.getEmailInvocations() would
            // read 0 if checked after.
            System.assertEquals(
                1,
                Limits.getEmailInvocations(),
                'Expected OpenCxOutboundEmailSender to queue one email'
            );
            Test.stopTest();
        }
    }
    ```

    <Note>
      Salesforce's `HttpCalloutMock` intercepts the `@future` webhook callouts so these tests don't need a live Named Credential or network access. `Test.startTest()` / `Test.stopTest()` flushes the queued `@future` methods synchronously.
    </Note>

    <Warning>
      **Keep `INTEGRATION_USERNAME` in sync across all four files** — `OpenCxOutboundEmailSender`, `OpenCxHumanAgentReplyTrigger`, `OpenCxOwnerChangeTrigger`, and `OpenSalesforceCaseManagementTest`. If they drift, the triggers stop firing for real traffic **and** the test silently skips the main assertion path (the `if (integrationUsers.isEmpty()) return` guard), which can mask the breakage behind a green test run.
    </Warning>

    Save with **Save** at the bottom, or in the Developer Console use **File → Save** (⌘S on Mac, Ctrl+S on Windows/Linux).

    After saving, run the tests: **Setup → Apex Test Execution → Select Tests → `OpenSalesforceCaseManagementTest`**. All tests should pass, and coverage on `OpenSalesforceCaseManagement` + the six triggers will report ≥ 75%.
  </Step>

  <Step title="Production readiness checklist">
    The six triggers + test class are enough to make the integration *function*. For a production deployment that won't surprise you in week two, also complete the following:

    **1. Dedicated integration user.** Don't OAuth as a named human. In **Setup → Users → Users**, clone the System Administrator profile and create a user named `OpenCX Integration`. OAuth as that user. When real humans leave the company and their logins are disabled, the integration keeps working.

    **2. Organization-Wide Email Address.** In **Setup → Email → Organization-Wide Addresses**, add `support@yourcompany.com` and verify it (Salesforce emails a verification link — click it from the target inbox). Then add one line to `OpenCxOutboundEmailSender` before `emails.add(mail)`:

    ```apex theme={"dark"}
    mail.setOrgWideEmailAddressId('0D2XXXXXXXXXXXX');  // Id of the verified OWA
    ```

    Without this, outbound AI replies go out from the integration user's personal Salesforce address. Customers see a weird-looking `From:` and spam filters flag it because the sender domain doesn't match your brand.

    **3. SPF on your sending domain.** Publish an SPF record on `yourcompany.com` that includes Salesforce:

    ```
    v=spf1 include:_spf.salesforce.com -all
    ```

    Without it, your outbound AI replies land in spam, and inbound forwarded mail to Salesforce can be rejected at the DMARC layer.

    **4. DKIM signing.** In **Setup → Email → DKIM Keys → Create New Key**, generate a key for your sending domain and publish the two CNAME records Salesforce gives you. Unsigned outbound mail gets aggressively spam-filtered by Gmail and Workspace.

    **5. Case Assignment Rules.** In **Setup → Case → Case Assignment Rules**, define rules that route incoming Cases to the right Queue based on sender domain, routing address, or keywords. This is what makes the "Case Owner = Queue" choice on the Routing Address actually pay off — Queues without rules are just static inboxes.

    **6. Email Deliverability.** **Setup → Email → Deliverability → Access level** must be `All email` (not `System email only`). Sandbox / trial defaults block all outbound — your Dev Edition tests will fail here first.

    **7. Daily email limits.** `Messaging.sendEmail` to external addresses is capped per org per GMT-day:

    | Edition | External email cap / day |
    | - | - |
    | Developer Edition / trial | 15 |
    | Sandbox | typically low, varies |
    | Enterprise / Unlimited / Performance | 5,000 |

    If production volume exceeds 5,000/day outbound, replace `Messaging.sendEmail` with an HTTP callout to an external ESP (SendGrid, Postmark, Mailgun) via a Named Credential — the trigger structure stays the same, only the sending primitive changes. Most support workloads stay well under the cap and don't need this.

    **8. Monitoring.** Turn on **Setup → Debug Logs** for the integration user before any production cutover. The `OpenCxOutboundEmailSender sendEmail failed:` lines captured here are your first signal when deliverability, limits, or deliverability settings regress.

    **9. Strengthen the test class with a behavioural assertion.** The supplied test class covers the trigger code paths (enough for Salesforce's ≥ 75% coverage requirement) but the `outboundEmailSender_queuesEmail` and `humanAgentReplyTrigger_firesOnOutgoingEmail` tests gate their assertions on the integration user existing in the test org. In a fresh sandbox that's fine; in a regression-sensitive production deploy, add a `@testSetup` that creates a dummy user matching `INTEGRATION_USERNAME` so the full send path is always exercised. Without this, refactors to the trigger body could regress silently while the test stays green.

    **10. Known gaps to track.** These are intentionally out of scope for the baseline trigger but worth queueing as follow-up work:

    * **Bounce handling.** Salesforce sets `EmailMessage.IsBounced = true` when the outbound message bounces. OpenCX isn't notified today — an additional trigger on `EmailMessage (after update)` should fire a `case_email_bounced` webhook so the dashboard flags the failed delivery.
    * **Idempotency.** If Salesforce re-fires the trigger for the same `EmailMessage` (bulk load, recovery), the customer receives duplicate copies. Add a custom boolean `OpenCx_Sent__c` on `EmailMessage` and set it in the trigger after `sendEmail` succeeds; short-circuit on the flag at the top of the loop.
    * **Rate limiting.** `Messaging.sendEmail` caps at 5,000/day in Enterprise. At higher volumes, swap the send primitive for an HTTP callout to an external ESP (SendGrid / Postmark / Mailgun) via a Named Credential — the trigger's filter/build logic stays the same.
  </Step>

  <Step title="Verify end to end">
    Send a test email to an address connected to OpenCX. Escalate the conversation (or ask to speak with a human). Within a few seconds:

    1. A Case appears in Salesforce with `Case_From__c` set to `opencx`.
    2. Reply on the Case from Salesforce.
    3. The reply appears as an agent message on the matching session in your [OpenCX Inbox](https://platform.open.cx/inbox).

    If any step fails, jump to [Troubleshooting](/integrations/salesforce/troubleshooting).
  </Step>
</Steps>

## How handoff lands in Salesforce

```mermaid theme={"dark"}
flowchart LR
  A[Contact emails] --> B{AI can resolve?}
  B -- Yes --> C[AI replies by email]
  B -- No --> D[Handoff]
  D --> E[Salesforce Case created]
  E --> F[Rep replies on the Case]
  F --> G[Reply syncs to contact inbox]
```

When <Tooltip href="/handoff/introduction">handoff</Tooltip> triggers, OpenCX:

1. Creates a Salesforce Case with the conversation topic as **Subject** and the AI summary as **Description**.
2. Sets `Case_From__c` to `opencx` so your views and reports can filter to AI-escalated cases.
3. Attaches the full transcript as Case comments.
4. Stores the Salesforce Case ID on the OpenCX session for tracing.
5. When your rep replies on the Case, the webhook fires and OpenCX delivers the reply to the contact's inbox.
6. When the Case is closed, the OpenCX session resolves.

<Note>
  If the same contact re-engages before the Case is closed, OpenCX appends to the existing Case instead of opening a new one.
</Note>

## Keeping the Case and the session in sync

Beyond replies, OpenCX keeps the Case and its OpenCX session consistent in both directions. The behavior below applies to the Email Cases (v2) integration only.

**Email-content intake separates current replies from history.** For workspaces configured by OpenCX to use incoming email content instead of the Case description, an existing Case starts from its latest incoming email. Earlier incoming emails are kept with their original timestamps, without triggering AI responses, message-received workflows, case updates, or ownership changes. If an earlier email’s attachments cannot be retrieved, session setup still completes and the import is retried on a later incoming-reply webhook. Subsequent incoming replies are processed normally. Repeated webhooks do not process an email already stored in the session again.

**Earlier agent activity stays in its original order.** When an existing Case first becomes an OpenCX session, up to ten agent emails and comments from before the incoming email that starts the session are imported with their original timestamps. Importing that history does not trigger a handoff, handoff field auto-fill, reply SLA completion, or a customer-inactivity workflow. A new agent reply still follows the session's normal handoff rules.

The following sync options are opt-in.

**Case fields → session attributes.** Every Case field OpenCX can read is mirrored onto the session as an `sf_case_<Field>` attribute (Contact fields as `sf_contact_<Field>`, configured related objects as `sf_<object>_<Field>`, e.g. `sf_reservation_Status__c`). The snapshot refreshes on every event OpenCX handles, **plus every two minutes** for any Case that changed in Salesforce since the last check — so a field a rep edits directly (Status, a reason picklist, anything) reaches OpenCX within a couple of minutes without a trigger, and the AI never reasons over a stale Case. That sweep is automatic — there is nothing to install for it. It reads the changed Cases themselves in bulk, up to 200 per API call rather than one call per edit, then refreshes each linked Case's Contact and configured related records exactly as the other events already do. A field cleared in Salesforce is removed from the session too. Each refresh that changes something fires the **Session Updated** workflow trigger with the keys that moved (`changedFields`) and, per change, the previous and new value (`changes`), so an agentic workflow can react to a Salesforce change — for example "when `sf_case_Status` changes to `Escalated`, notify the team". Values the AI may see are still governed by the AI Context filters; changes to those allowed fields also appear on the session timeline as a **Salesforce fields updated** entry that shows each field's previous and new value, who made the change in Salesforce (the Case's *Last Modified By*), and when.

**Session attributes → Case fields.** When a session attribute that names an updateable Case field changes on the OpenCX side — a workflow's **Update Session Attributes** step writing `sf_case_Priority`, or an agent editing `Priority` in the inbox — the Case is updated. Picklist values must match one of the field's active options (by value or label); anything the field cannot accept is dropped and logged rather than failing the update. `OwnerId` is never written this way — ownership follows assignee sync below.

**Agent replies carry the agent's identity.** A reply or internal note a rep writes in Salesforce shows up in the inbox under that rep: the comment's author is matched to the linked member (the same email-based link assignee sync uses), so their OpenCX name and profile picture render on the message — like HubSpot and Zendesk replies do. An author without a linked member shows their Salesforce display name.

**Members ↔ Salesforce users.** Members are matched to Salesforce Users by email. To bring your Salesforce agents in as members and link them in one go, open **Settings → Members → Invite Members** and choose **Add members from Salesforce** (Email-to-Case v2 orgs only; requires the assignee sync switch below to be on): it fetches the org's active Salesforce users, links existing members with the same email, and creates members for agents who have no account yet — with the roles selected in the same dialog. Roles are required to create members: a membership with no role has no permissions, so with none selected the run only links agents who already have an OpenCX account and reports every new agent as skipped. No invitation email is sent; they sign in with the same email. The user OpenCX is connected as, API-only users, users without an email, and an email shared by several users are skipped and listed with a reason. Linked members carry a **Salesforce** badge on the Members page. Links are also made lazily the first time an owner or assignee change matches by email.

The same run brings your **Case Queues** in as teams — the other kind of Case owner: each Queue that can own a Case gets a support-enabled OpenCX team named after it (an existing team with that name is reused) and is registered on that team under **Escalation teams**, so a Queue-owned Case has somewhere to route. Queues already registered on a team are left alone; a Queue whose name is already taken by another registration is skipped and listed.

**Case Owner ↔ session assignee.** One switch under **Settings → Ticketing → Salesforce assignee sync** (it sets the same two organization settings HubSpot and Zendesk use) turns this on in both directions:

* **Salesforce → OpenCX** — when a rep takes the Case in Salesforce, the session is handed off (as always) *and* assigned to the linked OpenCX teammate. Giving the Case back to the integration user hands the session back to the AI. Reassignments between reps follow along.
* **OpenCX → Salesforce** — when the session's assignee changes in OpenCX, `Case.OwnerId` follows: a teammate → their Salesforce User, the AI → the integration user, unassigned → the Queue registered on the session's team when it sits in one, else the owner the Case had before OpenCX took it. Teammates without a linked Salesforce User are skipped, never cleared.

A Case has **one** owner — a User *or* a Queue, never both — so while the switch is on the session follows the same rule: it is either a linked member's or its team's. Assigning a member (or the AI) in OpenCX takes the session out of its team and the Case out of its Queue; moving a session to a team unassigns it and hands the Case to that team's Queue; a Case handed to a Queue in Salesforce leaves the session unassigned in the mapped team. The inbox only offers members linked to a Salesforce user and teams linked to a Queue (anyone else could not own the Case — add them from Salesforce first), and teams are not auto-distributed: a Queue-owned Case waits for a rep to take it. None of this applies while the switch is off, or to any other ticketing system.

**Queues ↔ teams.** A Salesforce Queue registered under **Escalation teams** can point at an OpenCX team (`group_id`) — **Add members from Salesforce** does this for every Case Queue, and the API accepts `group_id` for manual registrations. With assignee sync on, a Case assigned to that Queue moves the session into that team (unassigned — see above), and a session left unassigned in that team hands the Case to the Queue; the same registration is what the AI's escalate-case tool uses to route to the Queue.

## Reading a Salesforce record in a workflow

The **Lookup Salesforce Record** workflow step reads one record from your Salesforce org by its ID. It takes a single input, the 15- or 18-character Record ID, typed in or mapped from an earlier step or a session attribute such as `sf_case_ContactId`. The ID tells the step which object the record belongs to, so the same step reads Cases, Contacts, Accounts, Users and custom objects.

The output has the record's 18-character ID (`id`), its object name (`type`) and its fields keyed by API name (`fields`), so a later step can use a value such as `fields.Status`. Fields that are empty in Salesforce are left out. The step uses this integration's connection and sees only what the integration user can see. An ID with no record, or a record that user can't open, fails the step with the reason.

## Changing the integration user (the AI's Salesforce seat)

Everything OpenCX writes to Salesforce — Case updates, Case comments, draft replies — is authored by **the Salesforce user who completed the OAuth connection**. There is no separate setting for it: the seat *is* whoever clicked **Allow**. OpenCX resolves that user from the token at runtime.

This also caps what the integration can do. An OAuth scope never grants more than the connecting user's own profile allows, so the seat's permissions — not the scope list — are the real limit.

### Switching to a different user

<Steps>
  <Step title="Sign in to Salesforce as the user you want the integration to run as">
    Use a private/incognito window, or log out of Salesforce first. The connect flow reuses whatever Salesforce session is already active in your browser — if you skip this, you will silently re-authorize the **same** seat and see no error.
  </Step>

  <Step title="Reconnect in OpenCX">
    In [Settings → Integrations](https://platform.open.cx/settings/integrations) → **Salesforce** → **Case Management**, click **Save and Connect** again. Your Consumer Key, Secret and Login URL stay as they are.
  </Step>

  <Step title="Approve">
    If prompted, sign in as the new user, then click **Allow**. New tokens replace the old ones. From that moment every Case update, Case comment and draft reply is authored by the new user.
  </Step>

  <Step title="Verify">
    Trigger a handoff (or reply on an existing AI-escalated Case) and confirm the resulting Case comment is authored by the new user.
  </Step>
</Steps>

### Requirements for the new user

A user who fails any of these cannot hold the seat:

| Requirement | Why |
| - | - |
| **Can log in through a browser** | OpenCX uses the OAuth authorization-code flow, which requires reaching the Salesforce approval screen interactively. |
| **Belongs to the org that owns the app** | Authorizing into a different org fails with `OAUTH_AUTHORIZATION_BLOCKED`. See [troubleshooting](/integrations/salesforce/troubleshooting). |
| **Authorized for the app** | If the app's permitted-users policy is **Admin approved users are pre-authorized**, assign the user's profile or a permission set to the app first. |
| **Has the object permissions below** | Missing permissions surface later as failed Case writes, not as a connection error. |
| **App's refresh token policy is *valid until revoked*** | Otherwise the connection dies when the access token expires — usually within hours. See [troubleshooting](/integrations/salesforce/troubleshooting). |

<Warning>
  **A Salesforce Integration License user (API Only) cannot be used.** That license blocks interactive login, and the authorization-code flow requires it. OpenCX does not support the JWT bearer or client-credentials flows that exist for API-only users. Use a dedicated **regular** user with a minimal profile instead — see the object permissions in [Setup](#setup).
</Warning>

<Note>
  Prefer a dedicated named user (for example `opencx-integration@yourcompany.com`) over a person's account. When an employee leaves and their user is deactivated, the integration stops with them.
</Note>

## Disconnecting

In OpenCX, open the Salesforce integration and click **Disconnect**. Then in Salesforce, delete the Named Credential (`OpenCX_Integration`) and the Apex Trigger/Class you created. Cases created while the integration was active remain untouched.

***

## Related Documentation

<CardGroup>
  <Card title="AI Email in Salesforce" icon="envelope" href="/integrations/salesforce/channels/email">
    Per-channel implementation details for email handoff.
  </Card>

  <Card title="Live Messaging" icon="messages" href="/integrations/salesforce/live-messaging">
    The path for chat, SMS, WhatsApp, and phone channels.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/salesforce/troubleshooting">
    OAuth errors, missing Cases, webhook issues.
  </Card>

  <Card title="Handoff settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Live Messaging
Source: https://docs.open.cx/integrations/salesforce/live-messaging

Route chat, SMS, WhatsApp, and phone handoffs from OpenCX into the Salesforce console via Messaging for In-App and Web.

<Tooltip>Messaging for In-App and Web</Tooltip> is the path for every real-time channel — web chat, SMS, WhatsApp, and phone. Conversations land in the Salesforce console as live messaging threads your reps pick up with the full AI transcript attached. For email, use [Email Cases](/integrations/salesforce/email-cases) instead.

<SalesforceLiveFlow />

<Info>
  Setup takes about 20 minutes. You need a Salesforce admin who has configured an <Tooltip>Embedded Service Deployment</Tooltip> with Omni-Channel routing, and admin access in OpenCX.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Salesforce edition with Messaging for In-App and Web" icon="circle-check">
    Service Cloud with Messaging for In-App and Web enabled. Contact your Salesforce admin if the Embedded Service Deployments section is missing from Setup.
  </Accordion>

  <Accordion title="Embedded Service Deployment configured" icon="gear">
    An Embedded Service Deployment must already exist in Salesforce with Omni-Channel routing configured. OpenCX connects to this deployment — it does not create one for you.
  </Accordion>

  <Accordion title="RSA key pair for JWT authentication" icon="lock">
    OpenCX signs identity tokens with an RSA private key. You register the matching public key in Salesforce. Generate the pair before starting setup.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="key">
    Required to save integration settings in [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Gather your Salesforce identifiers">
    You need three values from Salesforce Setup:

    | Identifier | Where to find it |
    | - | - |
    | **Instance URL** | Your Salesforce domain (e.g. `https://yourcompany.my.salesforce.com`). |
    | **ES Developer Name** | **Setup → Embedded Service Deployments** → select your deployment → copy the **API Name**. |
    | **Salesforce Org ID** | **Setup → Company Information → Organization ID**. |
  </Step>

  <Step title="Generate and register JWT keys">
    1. Generate an RSA key pair (2048-bit or higher).
    2. In Salesforce, open your Embedded Service Deployment's **Auth Key** settings and register the **public key** (PEM format).
    3. Note the **Auth Key ID** Salesforce assigns after registration — you need it in the next step.

    <Warning>
      Keep the private key secure. Anyone with the private key can sign identity tokens on behalf of your organization.
    </Warning>
  </Step>

  <Step title="Enter credentials in OpenCX">
    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), open **Salesforce** and choose **In-App Chat (MIAW)**.

    | Field | Value |
    | - | - |
    | **Instance URL** | Your Salesforce domain (include `https://`). |
    | **ES Developer Name** | The API name from your Embedded Service Deployment. |
    | **Salesforce Org ID** | The Organization ID from Company Information. |
    | **Auth Public Key** | The public key in PEM format (include `-----BEGIN PUBLIC KEY-----` headers). |
    | **Auth Private Key** | The private key in PEM format (include `-----BEGIN PRIVATE KEY-----` headers). |
    | **Auth Key ID** | The Key ID Salesforce assigned when you registered the public key. |

    Click **Save**.

    <Note>
      The private key is stored encrypted. After saving, the dashboard displays only a redacted preview — the full key is never shown again.
    </Note>
  </Step>

  <Step title="Verify end to end">
    Send a test message on a connected channel (web widget, WhatsApp, or SMS). Escalate the conversation.

    1. A messaging thread appears in the Salesforce console with the AI transcript.
    2. Reply from the Salesforce console.
    3. The reply lands back on the original channel within a couple of seconds.

    If any step fails, jump to [Troubleshooting](/integrations/salesforce/troubleshooting#live-messaging).
  </Step>
</Steps>

## How handoff lands in Salesforce

```mermaid theme={"dark"}
flowchart LR
  A[Contact message] --> B{AI can resolve?}
  B -- Yes --> C[AI replies on channel]
  B -- No --> D[Handoff]
  D --> E[Messaging thread in Salesforce]
  E --> F[Rep replies in console]
  F --> G[Reply lands on original channel]
```

When <Tooltip href="/handoff/introduction">handoff</Tooltip> triggers, OpenCX:

1. Generates a JWT identity token for the contact, signed with your private key.
2. Obtains a messaging access token from Salesforce.
3. Builds a transcript with the AI summary and conversation history.
4. Extracts routing attributes from the session — channel, language, priority, and session ID.
5. Creates a conversation in Salesforce with routing attributes attached.
6. Sends the transcript as the opening message so your rep has full context.
7. Rep replies sync back to the OpenCX session in real time.

<Note>
  OpenCX retries handoff up to 3 times with increasing delays if Salesforce is temporarily unreachable.
</Note>

## Routing attributes

OpenCX attaches these attributes to every messaging conversation. Your <Tooltip>Omni-Channel</Tooltip> flow can read them for routing decisions.

| Attribute | Value | Purpose |
| - | - | - |
| `OpencxSessionId` | Session UUID | Trace back to the OpenCX session. |
| `Chat_Consumer_Type` | `Consumer - Authenticated` or `Consumer - Non-Authenticated` | Differentiate identified vs anonymous contacts. |
| `Origin` | `MIABOT` | Identifies conversations that came from OpenCX. |
| `Priority` | `Low` (default) | Baseline routing priority. |
| `Chat_language` | Detected language code | Route to language-specific queues. |

<Info>
  Additional attributes may populate from session and contact data depending on your organization's configuration. Your Omni-Channel flow must reference the attribute names to use them for routing.
</Info>

## Disconnecting

In OpenCX, open the Salesforce integration, choose **In-App Chat (MIAW)**, and click **Delete**. Active conversations finish on their current channel; no data is deleted from Salesforce.

***

## Related Documentation

<CardGroup>
  <Card title="Channels" icon="grid-2" href="/integrations/salesforce/channels/widget">
    Per-channel implementation details for Widget, WhatsApp, SMS, Phone, and Email.
  </Card>

  <Card title="Email Cases" icon="envelope" href="/integrations/salesforce/email-cases">
    The companion path for email handoff.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/salesforce/troubleshooting">
    Access token errors, missing conversations, routing issues.
  </Card>

  <Card title="Handoff settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Salesforce overview
Source: https://docs.open.cx/integrations/salesforce/overview

Route email cases and live conversations from OpenCX to Salesforce Service Cloud agents.

OpenCX works alongside your agents inside Salesforce Service Cloud. The AI resolves what it can, escalates what it can't, and files every handoff straight into a <Tooltip>Case</Tooltip> or live messaging thread your reps already work in — no separate inbox, no context rebuild.

<Tip>
  Setup starts at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="Cases your reps pick up with full context" icon="ticket">
    When the AI escalates an email conversation, OpenCX creates a Salesforce Case with the conversation summary as the description and the full transcript attached as comments. Rep replies on the Case sync back to the contact's inbox.
  </Accordion>

  <Accordion title="Live conversations routed to your reps in real time" icon="messages">
    Chat, SMS, WhatsApp, and phone handoffs land in the Salesforce console as <Tooltip>Messaging for In-App and Web</Tooltip> threads with the AI transcript attached. Your reps pick up where the AI left off.
  </Accordion>

  <Accordion title="Session data mapped to routing attributes" icon="route">
    Channel, language, priority, and session ID flow into Salesforce as <Tooltip href="/integrations/salesforce/live-messaging#routing-attributes">routing attributes</Tooltip> so Omni-Channel routes each conversation to the right queue without manual triage.
  </Accordion>

  <Accordion title="Every answer grounded in your training data" icon="book">
    Reps see the conversation summary and the AI's reasoning to continue where the AI stopped. No guessing what the customer already tried.
  </Accordion>
</AccordionGroup>

## Supported channels

Pick the channel you want to wire through Salesforce — each page covers the implementation details for that channel on top of the shared setup.

<CardGroup>
  <Card title="AI Chat Widget" icon="comments" href="/integrations/salesforce/channels/widget">
    Live chat handoff into the Salesforce console via Messaging.
  </Card>

  <Card title="AI WhatsApp Support" icon="whatsapp" href="/integrations/salesforce/channels/whatsapp">
    Business WhatsApp threads routed to your reps.
  </Card>

  <Card title="AI SMS Support" icon="comment-sms" href="/integrations/salesforce/channels/sms">
    Inbound SMS handed off as live messaging conversations.
  </Card>

  <Card title="AI Phone Support" icon="phone" href="/integrations/salesforce/channels/phone">
    Voice conversations with transcript attached for your reps.
  </Card>

  <Card title="AI Email Support" icon="envelope" href="/integrations/salesforce/channels/email">
    Email handoff creates a Salesforce Case with the thread attached.
  </Card>
</CardGroup>

## Observability

Every conversation OpenCX hands to Salesforce is traceable from the Salesforce side back to the exact OpenCX session. Your reps debug in the tool they're already in; your admins audit without re-running the AI.

<AccordionGroup>
  <Accordion title="Session ID on every case and conversation" icon="fingerprint">
    For email, OpenCX stores the Salesforce Case ID on the OpenCX session (`salesforce_case_id`). For live messaging, the conversation is created with the OpenCX session ID as the external identifier (`salesforce_miaw_session_id`). Both are searchable from either side.
  </Accordion>

  <Accordion title="Case and routing markers" icon="tag">
    Cases get `Case_From__c` set to `opencx` so you can filter views and reports to AI-escalated cases. Live messaging conversations carry routing attributes — `OpencxSessionId`, `Chat_Consumer_Type`, `Origin`, `Priority`, and `Chat_language` — readable in your Omni-Channel flow and analytics.
  </Accordion>

  <Accordion title="Handoff debug events in OpenCX" icon="bug">
    Every handoff logs a debug event with routing attributes and transcript data, visible in the session detail in your [OpenCX Inbox](https://platform.open.cx/inbox). Click any session to see the full AI reasoning, tool calls, and handoff context.
  </Accordion>
</AccordionGroup>

## Pick your setup path

Two paths, one for email and one for everything real-time. Most teams start with one and add the other later.

<Tabs>
  <Tab title="Email (Cases)">
    Use the Case Management path for **email**. OpenCX creates a Salesforce Case on handoff and syncs your reps' replies back to the contact's inbox.

    Credentials: a <Tooltip>Connected App</Tooltip> with OAuth 2.0 (Consumer Key, Consumer Secret, Login URL).

    <Card title="Set up Email Cases" icon="envelope" href="/integrations/salesforce/email-cases">
      Create the Connected App, connect OAuth, and configure the webhook.
    </Card>
  </Tab>

  <Tab title="Live Messaging">
    Use the <Tooltip>Messaging for In-App and Web</Tooltip> path for every real-time channel — web chat, SMS, WhatsApp, and phone. Conversations land in the Salesforce console as live messaging threads.

    Credentials: Instance URL, <Tooltip>ES Developer Name</Tooltip>, Salesforce Org ID, and an RSA key pair for JWT authentication.

    <Card title="Set up Live Messaging" icon="messages" href="/integrations/salesforce/live-messaging">
      Register your keys and connect Messaging for In-App and Web.
    </Card>
  </Tab>
</Tabs>

<Note>
  You can enable both paths. Email handoffs create Cases; chat, SMS, WhatsApp, and phone handoffs route through live messaging.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Email Cases" icon="envelope" href="/integrations/salesforce/email-cases">
    OAuth setup, webhook, and Apex configuration for email.
  </Card>

  <Card title="Live Messaging" icon="messages" href="/integrations/salesforce/live-messaging">
    JWT setup for chat, SMS, WhatsApp, and phone.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/salesforce/troubleshooting">
    Connection failures, missing cases, routing issues.
  </Card>
</CardGroup>


# Salesforce troubleshooting
Source: https://docs.open.cx/integrations/salesforce/troubleshooting

Debug Salesforce connection, case creation, live messaging handoff, and agent reply sync issues.

Before debugging, have this ready:

* Admin access to both your Salesforce org and your [OpenCX dashboard](https://platform.open.cx/settings/integrations).
* A specific session ID (from [Inbox](https://platform.open.cx/inbox)) or Salesforce Case ID where the problem shows.
* The webhook URL shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Salesforce (for email issues).

<Tip>
  Check connection status in [**Settings → Integrations**](https://platform.open.cx/settings/integrations) → Salesforce as your first step. Most issues are credential or configuration related.
</Tip>

## Email Cases

Jump to the symptom that matches what you're seeing.

### **"OAuth credentials won't save"**

<Tooltip>Likely cause</Tooltip>: Connected App still activating, or credentials copied incorrectly.

**Fix:** wait 2–10 minutes after creating the Connected App, then retry. Re-copy the Consumer Key and Consumer Secret without leading or trailing spaces. Confirm the Login URL is `https://login.salesforce.com` (production) or `https://test.salesforce.com` (sandbox).

### **"Connect to Salesforce fails"**

<Tooltip>Likely cause</Tooltip>: callback URL mismatch or popup blocked.

**Fix:** in Salesforce, open the Connected App and confirm the callback URL is exactly:

```
https://api.open.cx/backend/salesforce-case-management/oauth/callback
```

Allow popups for `platform.open.cx` in your browser.

### **"OAUTH\_APPROVAL\_ERROR\_GENERIC after logging in to Salesforce"**

Salesforce shows *"We can't authorize you because of an OAuth error … OAUTH\_APPROVAL\_ERROR\_GENERIC : An unexpected error has occurred during authentication."*

<Tooltip>Likely cause</Tooltip>: a scope mismatch between what OpenCX requests and what the app grants. The common case: the app is an **External Client App** (which cannot grant `Full access (full)`) while the OpenCX workspace still requests `full` — the historical default.

**Fix:**

1. Using an External Client App? Ask OpenCX to switch your workspace to the least-privilege scope set (`api id refresh_token offline_access`), and select exactly the three matching checkboxes on the app — see [Create an External Client App](/integrations/salesforce/email-cases#setup).
2. Using a classic Connected App? Make sure every scope OpenCX requests is selected on the app (`Full access` + `Perform requests at any time` for the default configuration).
3. If you recreated the app, paste the **new** Consumer Key and Secret into OpenCX and save — retrying with the old app's saved credentials keeps failing the same way. Wait 2–10 minutes after app creation, then **Save and Connect** again.

### **"error=invalid\_client\_id when redirected to Salesforce"**

<Tooltip>Likely cause</Tooltip>: the app was created moments ago, or the Consumer Key was copied incorrectly.

**Fix:** wait 2–10 minutes and retry. If it persists, re-copy the Consumer Key (no whitespace) and confirm the Login URL points at the org that owns the app — for a sandbox use `https://test.salesforce.com`, or use your org's My Domain URL directly.

### **"OAUTH\_AUTHORIZATION\_BLOCKED — Cross-org OAuth flows are not supported for this external client app"**

<Tooltip>Likely cause</Tooltip>: you authorized into a different Salesforce org than the one that owns the app. A generic Login URL (`https://test.salesforce.com` or `https://login.salesforce.com`) sends you to whichever org your credentials resolve to, which need not be the app's org.

**Fix:**

1. Set the **Login URL** to the **My Domain URL of the org that owns the app** — for example `https://yourorg--sandboxname.sandbox.my.salesforce.com`. This pins the flow to one org and is the single most common fix.
2. If it still fails, the app genuinely lives elsewhere. An External Client App cannot be reused across orgs unless it is packaged and distributed, so create the app **inside** the org you are connecting.
3. Leaving the Login URL blank silently defaults to **production** — a frequent cause when you meant to connect a sandbox.

### **"Connection works, then stops a few hours later"**

Cases stop creating sessions and rep replies stop syncing. OpenCX logs `Unable to refresh session due to: expired access/refresh token`, and reconnecting fixes it only until the next token expiry.

<Tooltip>Likely cause</Tooltip>: the app's refresh token policy expires the refresh token.

**Fix:** in the app's OAuth policies, set the **Refresh Token Policy** to **Refresh token is valid until revoked**, then reconnect once. Also confirm the app grants **Perform requests at any time** (`refresh_token`, `offline_access`) — without it no usable refresh token is ever issued.

### **"Case comments and replies are authored by the wrong Salesforce user"**

<Tooltip>Likely cause</Tooltip>: the integration is connected as the wrong user.

**Fix:** log out of Salesforce (or use a private window), sign in as the user you want, then **Save and Connect** again. Full steps and the requirements that user must meet are in [Changing the integration user](/integrations/salesforce/email-cases#changing-the-integration-user-the-ais-salesforce-seat).

### **"Case created in Salesforce but no session appears in OpenCX"**

<Tooltip>Likely cause</Tooltip>: the `@future` webhook callout is failing inside Salesforce.

**Fix:**

1. **Setup → Apex Jobs** — find the failed future jobs from your test; the error column names the exact cause.
2. **Setup → Named Credentials** — the **Name** must exactly match the `callout:` reference in the Apex class (`OpenCX_Integration` by default), and the URL must be the **base** Webhook URL from the OpenCX dashboard: everything up to and including `/webhook`, with the token segment removed.
3. **The token must reach us as a header.** Confirm the Apex class sets `x-opencx-token` (or `Authorization: Bearer`) and that the value it reads is populated — an empty protected Custom Setting yields a blank header and the webhook is rejected with `Missing webhook token`. A token left in the URL path still works, but it leaks into debug logs and Apex Jobs entries; move it to the header.
4. Passing Apex tests do **not** prove this path — tests mock the callout (`HttpCalloutMock`), so a broken Named Credential still shows green tests.

### **"Emails to my support address never create a Case"**

<Tooltip>Likely cause</Tooltip>: the forward from your support mailbox to the long `...case.salesforce.com` address isn't confirmed, or the Routing Address isn't verified.

**Fix:** in **Setup → Email-to-Case → Routing Addresses**, the address must show **Verified**. Then confirm the mailbox forward itself (e.g. Gmail's forwarding confirmation — the code lands in Salesforce as an EmailMessage; see Email Cases Step 3). Emails sent directly to the long Email Services Address bypass forwarding — if those create Cases but your support address doesn't, the forward is the broken link.

### **"Handoff runs but no Case appears in Salesforce"**

<Tooltip>Likely cause</Tooltip>: Apex trigger not deployed or inactive, Named Credential misconfigured.

**Fix:**

1. In Salesforce **Setup → Apex Triggers**, confirm `CaseTrigger` is active.
2. In **Setup → Named Credentials**, confirm `OpenCX_Integration` points to the base webhook URL from OpenCX — no token segment (re-copy if it looks stale).
3. In **Setup → Apex Classes**, confirm `OpenSalesforceCaseManagement` is saved and active.

### **"AI replies show as sent in OpenCX but the contact never receives the email"**

<Tooltip>Likely cause</Tooltip>: outbound delivery trigger not deployed, or org-wide email deliverability blocked.

A plain `EmailMessage` insert in Salesforce creates a record in the Case Feed but does not actually transmit the email — transmission requires `Messaging.sendEmail()` via the `OpenCxOutboundEmailSender` trigger. If the trigger is missing, the AI reply logs to the Case Feed (showing Status `Sent`) but never leaves Salesforce.

**Fix:**

1. In Salesforce **Setup → Apex Triggers**, confirm `OpenCxOutboundEmailSender` exists, is **Active**, and targets `EmailMessage`. If missing, deploy it per [Email Cases → Step 3, Trigger 5](/integrations/salesforce/email-cases#apex-triggers).
2. In **Setup → Email → Deliverability**, confirm **Access level** is `All email` (not `System email only` or `No access`).
3. Confirm the integration user's profile has the **Send Email** permission.
4. Re-send the AI reply from OpenCX. It should now land in the contact's inbox.

Run `SELECT Id, CreatedDate, FromAddress, ToAddress, Status FROM EmailMessage WHERE ParentId = '<caseId>' AND Incoming = false ORDER BY CreatedDate DESC` to confirm outbound records exist in Salesforce. If they do but the contact still doesn't receive the email, enable a **Debug Log** for the integration user (**Setup → Debug Logs → New** with the integration user as Traced Entity), re-send the reply from OpenCX, then open the resulting log and look for the `EmailMessage` insert transaction — confirm `OpenCxOutboundEmailSender` executed and didn't throw. If it didn't run, double-check in **Setup → Apex Triggers** that the trigger is still **Active**.

### **"Customer replies open a duplicate Case instead of threading into the original"**

<Tooltip>Likely cause</Tooltip>: `OpenCxOutboundEmailSender` is missing the call to `EmailMessages.getFormattedThreadingToken(em.ParentId)`, or an older version of the trigger is deployed.

**Fix:** update `OpenCxOutboundEmailSender` to the version documented at [Email Cases → Trigger 5](/integrations/salesforce/email-cases#apex-triggers). The current version appends the threading token to both the subject and the body, which is what Email-to-Case (Summer '22+) uses to attach customer replies to the same Case.

You can confirm by opening a recent outbound `EmailMessage` record on the Case Feed and checking its Subject/Body — you should see a `ref:!...:ref` token at the end. If the token isn't there, the trigger is stale.

### **"Customer replies never reach Salesforce at all"**

<Tooltip>Likely cause</Tooltip>: `REPLY_TO_ADDRESS` not set on the outbound trigger, or the reply-to address isn't registered as a verified Routing Address.

**Fix:**

1. In `OpenCxOutboundEmailSender`, confirm `REPLY_TO_ADDRESS` is set to your customer-facing forwarding address (e.g. `support@yourcompany.com`). Without `setReplyTo()`, replies go to the integration user's personal Salesforce inbox and never reach Email-to-Case.
2. In **Setup → Service → Email-to-Case → Routing Addresses**, confirm that same address is listed and its status is **Verified**. Until verified, Salesforce drops forwarded mail silently.
3. Confirm the forwarding itself works: send a plain email to your forwarding address, then check **Setup → Email Logs** — if no delivery record appears within 30 minutes, the forward is failing before it reaches Salesforce (usually SPF / DMARC). Publish an SPF record on your domain that includes `_spf.salesforce.com`, or switch to an SRS-aware forwarder.

### **"Hit `SINGLE_EMAIL_LIMIT_EXCEEDED` in the Debug Log"**

<Tooltip>Likely cause</Tooltip>: the org's external email cap for the GMT day is exhausted.

**Fix:**

1. Wait for midnight GMT — the counter resets automatically, no code change required.
2. If you're doing heavy iteration in a Developer / trial org (15/day cap), move testing to an Enterprise/Unlimited sandbox (5,000/day). The limit is a hardcoded edition characteristic — it cannot be raised on Dev Edition.
3. For high-volume production workloads that exceed 5,000/day, replace `Messaging.sendEmail` in `OpenCxOutboundEmailSender` with an HTTP callout to an external ESP (SendGrid / Postmark / Mailgun) via a Named Credential.

Note that `setTargetObjectId(contactId)` **does not** bypass this limit for external recipients — that optimisation only applies when the target is a Salesforce User record.

### **"Gmail forwarding stuck at `Unverified`"**

<Tooltip>Likely cause</Tooltip>: Gmail's forwarding handshake sent a verification code to Salesforce's long `@...case.salesforce.com` address; Salesforce received it as a new Case but you didn't retrieve the code to paste back into Gmail.

**Fix:**

1. In Gmail → **Settings → Forwarding and POP/IMAP** → click **Re-send email** next to the pending Salesforce address (sends a fresh code).

2. In Developer Console → Query Editor:

   ```sql theme={"dark"}
   SELECT Id, Subject, TextBody, CreatedDate
   FROM EmailMessage
   WHERE FromAddress = 'forwarding-noreply@google.com'
   ORDER BY CreatedDate DESC
   LIMIT 1
   ```

3. Open the newest row and copy the 9-digit confirmation code from the `TextBody`.

4. Paste the code into Gmail's verification input → **Verify**. Status should flip to `Confirmed` and forwarding is live.

The same pattern works for other mail providers (Outlook, FastMail, custom domains) — send a fresh verification, then pull the code from the newest `EmailMessage` in Salesforce.

### **"Rep replies don't reach the contact"**

<Tooltip>Likely cause</Tooltip>: webhook not firing or Named Credential URL outdated.

**Fix:** re-copy the webhook URL from [Settings → Integrations](https://platform.open.cx/settings/integrations) → Salesforce and update the Named Credential. Confirm the Apex trigger fires on Case `after insert`.

## Live Messaging

### **"MIAW settings won't save"**

<Tooltip>Likely cause</Tooltip>: Instance URL format wrong or PEM encoding incomplete.

**Fix:** include `https://` in the Instance URL (e.g. `https://yourcompany.my.salesforce.com`). Ensure PEM keys include the `-----BEGIN PUBLIC KEY-----` and `-----BEGIN PRIVATE KEY-----` header and footer lines.

### **"Handoff fails with access token error"**

<Tooltip>Likely cause</Tooltip>: key mismatch or wrong Auth Key ID.

**Fix:** regenerate the RSA key pair, re-register the public key in your Salesforce Embedded Service Deployment's Auth Key settings, copy the new Auth Key ID, and update all six fields under **In-App Chat (MIAW)** in OpenCX.

### **"Conversation created but no messages appear"**

<Tooltip>Likely cause</Tooltip>: ES Developer Name mismatch or Omni-Channel not set up.

**Fix:** in Salesforce **Setup → Embedded Service Deployments**, copy the exact **API Name** (case-sensitive) and paste it into the ES Developer Name field in OpenCX. Confirm that Omni-Channel routing is configured for this deployment.

### **"Routing attributes missing in Salesforce"**

<Tooltip>Likely cause</Tooltip>: Omni-Channel flow not reading the attributes.

**Fix:** in Salesforce **Setup → Omni-Channel Flows**, verify your flow references the attribute names (`OpencxSessionId`, `Chat_Consumer_Type`, `Origin`, `Priority`, `Chat_language`). Attributes are only useful if your flow reads them.

### Still stuck?

If none of the above resolves the issue, open a support request with:

* The session ID from [Inbox](https://platform.open.cx/inbox).
* The error message or unexpected behavior.
* Screenshots of your Salesforce setup (Named Credential, Apex Trigger status, or MIAW Embedded Service Deployment).

## Limits & timing

| | Value |
| - | - |
| **Connected App activation** | 2–10 minutes after creation |
| **Handoff retries** | 3 attempts with increasing delays |
| **Transcript length** | Up to 4,000 characters per handoff message |
| **Private key display** | Redacted after first save — re-enter to change |

***

## Related Documentation

<CardGroup>
  <Card title="Salesforce overview" icon="cloud" href="/integrations/salesforce/overview">
    Capabilities, supported channels, observability.
  </Card>

  <Card title="Email Cases" icon="envelope" href="/integrations/salesforce/email-cases">
    Re-verify OAuth, webhook, and Apex setup.
  </Card>

  <Card title="Live Messaging" icon="messages" href="/integrations/salesforce/live-messaging">
    Re-verify JWT credentials and routing attributes.
  </Card>

  <Card title="Handoff settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# AI Actions
Source: https://docs.open.cx/integrations/shopify/ai-actions

Configure which Shopify actions the AI can perform during conversations — order lookup, product search, and shop details.

Once your store is [connected](/integrations/shopify/connect), the AI gains three actions it can call during conversations. Each action is enabled by default and can be toggled independently.

## Available actions

<AccordionGroup>
  <Accordion title="Get Order Details" icon="box">
    The AI looks up an order by its order number (e.g. `#1042`, `UK-1003`).

    **What the customer sees:** order status, line items, fulfillment and tracking information, shipping address — the same data a rep would read from the Shopify admin.

    **Privacy guard:** the AI verifies that the customer's email matches the email on the order before revealing details. If the emails don't match, the AI declines the request.

    Requires the `read_orders` scope.
  </Accordion>

  <Accordion title="Search Products" icon="magnifying-glass">
    The AI searches your product catalog by keywords. It uses Shopify's native product search and returns results ranked by relevance.

    **What the customer sees:** matching product names, prices, availability, and descriptions. Useful for pre-sale questions like "do you have black running shoes in size 10?"

    Requires the `read_products` scope.
  </Accordion>

  <Accordion title="Get Shop Details" icon="store">
    The AI retrieves general information about your store — name, description, currency, shipping countries, and supported payment methods.

    **What the customer sees:** factual answers about your store's policies, accepted currencies, and shipping regions. Helpful for questions like "do you ship to Germany?" or "which payment methods do you accept?"

    Requires the `read_products` scope.
  </Accordion>
</AccordionGroup>

## Toggling actions

Each action can be enabled or disabled per organization. Disabled actions are not available to the AI during conversations.

Toggle actions in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Shopify under **Actions Settings**:

| Action | Default | When to disable |
| - | - | - |
| **Get Order Details** | Enabled | If you handle order inquiries through a separate system or want the AI to hand off order questions to a rep. |
| **Search Products** | Enabled | If your catalog is private or you prefer the AI not to recommend products. |
| **Get Shop Details** | Enabled | Rarely needed — only if shop-level data should not be shared in conversations. |

## Multi-store behavior

How the AI handles actions depends on the number of connected stores:

* **Single store:** every action runs against that store directly. No store selection needed.
* **Multiple stores:** the AI identifies the correct store from context — the customer's order number prefix, the store they mention, or the email match. When the customer asks about an order from a specific store, the AI routes the lookup to the right one.

<Note>
  Using distinct **order number prefixes** per store (e.g. `UK-` for your UK store, `NL-` for your Dutch store) makes multi-store routing more reliable. Configure prefixes in your Shopify admin under **Settings → General → Order processing**.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Store" icon="plug" href="/integrations/shopify/connect">
    Custom app, scopes, and credentials setup.
  </Card>

  <Card title="Contact Metadata" icon="address-card" href="/integrations/shopify/contact-metadata">
    Customer and order data in the inbox sidebar.
  </Card>

  <Card title="Shopify Overview" icon="shopify" href="/integrations/shopify/overview">
    Full integration capabilities at a glance.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/shopify/troubleshooting">
    Actions not firing, wrong store, missing data.
  </Card>
</CardGroup>


# Connect Shopify
Source: https://docs.open.cx/integrations/shopify/connect

Create a Shopify custom app with the required scopes and connect your store to OpenCX.

The store connection gives OpenCX real-time access to your Shopify Admin API. Once connected, the AI can look up orders, search products, and your reps see customer metadata in the inbox sidebar.

<ShopifyFlow />

<Info>
  Setup takes about 10 minutes per store. You need admin access to both your Shopify store and your OpenCX organization.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Shopify store with custom app support" icon="circle-check">
    Your Shopify plan must support custom app development. This is available on all current Shopify plans. If you don't see **Develop apps** in your Shopify admin, your store owner may need to enable it first.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="key">
    Required to save integration settings in [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Accordion>
</AccordionGroup>

<Warning>
  **Disable order auto-archival before connecting.** Archived orders are not queryable through the Shopify API. The AI will not be able to look up archived orders.

  In your Shopify admin, go to **Settings → General → Order processing** and uncheck **Automatically archive the order**.

  <video />
</Warning>

## Setup

<Steps>
  <Step title="Enable custom app development">
    In your Shopify admin, go to **Settings → Apps and sales channels → Develop apps**. You can also type *"Build custom apps"* in the search bar.

    Click **Allow custom app development** and confirm.
  </Step>

  <Step title="Create a custom app">
    Click **Create an app**. Name it `OpenCX` (or anything recognizable), then click **Create app**.

    <video />
  </Step>

  <Step title="Configure Admin API scopes">
    Click **Overview → Configure Admin API Scopes** (or **Configuration → Admin API integration → Configure**).

    Enable the following scopes:

    | Scope | Purpose |
    | - | - |
    | `read_orders` | Order lookup by order number |
    | `read_products` | Product catalog search |
    | `read_customers` | Customer metadata in the inbox sidebar |

    Click **Save**.

    <video />
  </Step>

  <Step title="Install the app and reveal the token">
    Go to **API Credentials → Access tokens** and click **Install app**. Confirm by clicking **Install** in the dialog.

    Click **Reveal token once** to display the <Tooltip>Admin API access token</Tooltip>. Copy it immediately.

    <Warning>
      The token is shown **only once**. If you lose it, you must uninstall and reinstall the app to generate a new one. Treat it like a password.
    </Warning>
  </Step>

  <Step title="Copy your Shopify domain">
    Your Shopify domain is the `*.myshopify.com` address for your store (e.g. `example.myshopify.com`). You can find it in the top-left corner of the **Settings** section in your Shopify admin.

    <video />
  </Step>

  <Step title="Save credentials in OpenCX">
    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), go to **Settings → Integrations** and find **Shopify**.

    | Field | Value |
    | - | - |
    | **Shopify domain** | Your `*.myshopify.com` domain. Include `.myshopify.com` — do not use your custom storefront domain. |
    | **Access token** | The Admin API access token you copied in the previous step. |

    Click **Save**. OpenCX validates the token and checks that the required scopes are granted before saving.
  </Step>

  <Step title="Verify the connection">
    After saving, open a conversation in the [inbox](https://platform.open.cx/inbox) where the contact's email matches a customer in your Shopify store. The sidebar should display the customer's profile and order history.

    If the sidebar is empty, check [Troubleshooting](/integrations/shopify/troubleshooting).
  </Step>
</Steps>

## Adding more stores

You can connect multiple Shopify stores to the same OpenCX organization. Each store has its own domain and access token.

In [Settings → Integrations](https://platform.open.cx/settings/integrations) → Shopify, click **Add Another Store** and repeat the setup steps above for each additional store. The AI routes lookups to the correct store automatically.

<Note>
  For multi-store setups, consider using **order number prefixes** (e.g. `UK-1001`, `DE-1002`) in your Shopify stores. This helps the AI identify which store an order belongs to when a customer provides their order number.
</Note>

## Rotating the access token

If a token is compromised or needs rotation:

1. In your Shopify admin, uninstall the custom app.
2. Reinstall it to generate a new token.
3. Update the token in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Shopify.

The old token stops working immediately on uninstall.

## Disconnecting

In OpenCX, open [Settings → Integrations](https://platform.open.cx/settings/integrations) → Shopify and delete the store connection. Then in your Shopify admin, uninstall the custom app if you no longer need it.

***

## Related Documentation

<CardGroup>
  <Card title="AI Actions" icon="robot" href="/integrations/shopify/ai-actions">
    What the AI can do with your store data and how to toggle actions.
  </Card>

  <Card title="Contact Metadata" icon="address-card" href="/integrations/shopify/contact-metadata">
    Customer and order data in the inbox sidebar.
  </Card>

  <Card title="Knowledge Base Sync" icon="book" href="/knowledge/sources/shopify/connect">
    Train the AI on your store pages, articles, and products.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/shopify/troubleshooting">
    Connection errors, missing scopes, token issues.
  </Card>
</CardGroup>


# Contact Metadata
Source: https://docs.open.cx/integrations/shopify/contact-metadata

See Shopify customer profiles and order history in the inbox sidebar for every conversation.

When a contact's email matches a customer in one of your connected Shopify stores, the [inbox](https://platform.open.cx/inbox) sidebar automatically displays their Shopify profile and recent orders. No extra setup beyond the [store connection](/integrations/shopify/connect) is needed — the `read_customers` scope enables this.

## What reps see

The sidebar shows a **Shopify** section for each connected store where the contact's email matches a customer record.

### Customer profile

* Customer name and email
* Number of orders placed
* Account creation date
* Direct link to the customer's page in Shopify Admin

### Order history

For each recent order (up to 50 per store):

* Order number and status (e.g. fulfilled, unfulfilled, partially fulfilled)
* Line items with product names and quantities
* Fulfillment and tracking information
* Order creation date
* Direct link to the order in Shopify Admin

<Note>
  Reps can click the customer or order links to jump directly into the Shopify Admin for actions that the integration doesn't handle — refunds, order edits, customer notes, etc.
</Note>

## Multi-store display

If the contact matches customers in multiple connected stores, the sidebar shows a separate section per store. Each section is labeled with the store's Shopify domain so reps can tell them apart at a glance.

## How matching works

OpenCX matches the **contact's email** against Shopify's customer email. If there is no match:

* The sidebar section is empty (no error shown).
* Make sure the contact has an email set in OpenCX and that the same email exists as a customer in your Shopify store.

<Info>
  Contact metadata is cached for **1 minute** to keep the sidebar responsive. If you update a customer or order in Shopify, the change appears in the inbox within a minute on the next sidebar load.
</Info>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Store" icon="plug" href="/integrations/shopify/connect">
    Ensure the `read_customers` scope is enabled.
  </Card>

  <Card title="AI Actions" icon="robot" href="/integrations/shopify/ai-actions">
    What the AI can do with your store data during conversations.
  </Card>

  <Card title="Shopify Overview" icon="shopify" href="/integrations/shopify/overview">
    Full integration capabilities at a glance.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/shopify/troubleshooting">
    Sidebar empty, customer not found, stale data.
  </Card>
</CardGroup>


# Shopify overview
Source: https://docs.open.cx/integrations/shopify/overview

Connect your Shopify store so the AI resolves order inquiries, searches products, and enriches every conversation with customer data.

OpenCX connects to your Shopify store's Admin API. The AI answers order-status questions, searches your product catalog, and pulls customer history into every conversation your reps handle — across every channel, without leaving the [inbox](https://platform.open.cx/inbox).

<Tip>
  Setup starts at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="Order status answered in the conversation" icon="box">
    Customers ask "where is my order?" and the AI looks it up by order number in real time. No tab-switching, no copying order IDs between systems. The AI verifies the customer's email before revealing details.
  </Accordion>

  <Accordion title="Product search and recommendations" icon="magnifying-glass">
    The AI searches your Shopify catalog by keyword and returns matching products with prices, availability, and links. Useful for pre-sale questions and upsell opportunities.
  </Accordion>

  <Accordion title="Customer data in every inbox conversation" icon="address-card">
    When a contact's email matches a Shopify customer, the inbox sidebar shows their profile, order history, and direct links to the Shopify Admin — scoped per store when you have multiple connected.
  </Accordion>

  <Accordion title="Your store content trains the AI" icon="book">
    Sync your Shopify pages, blog articles, and product descriptions into the AI's knowledge base. Edits propagate on the next scheduled sync — no manual re-training.
  </Accordion>

  <Accordion title="Multiple stores on one organization" icon="store">
    Connect as many Shopify stores as you need. The AI routes to the right store automatically. Teams with regional storefronts or separate warehouses run them all from one OpenCX organization.
  </Accordion>
</AccordionGroup>

## Pick your setup path

Most teams start with the store connection (AI actions + inbox enrichment) and add knowledge base sync later.

<Tabs>
  <Tab title="Store Connection">
    Connect your Shopify store with an Admin API access token. This enables the AI to look up orders, search products, and pull customer metadata into the inbox sidebar.

    Credentials: your `*.myshopify.com` domain and a <Tooltip>private access token</Tooltip> with the right scopes.

    <Card title="Connect your Shopify store" icon="plug" href="/integrations/shopify/connect">
      Create the custom app, set scopes, and save credentials.
    </Card>
  </Tab>

  <Tab title="Knowledge Base Sync">
    Sync your store's pages, blog articles, and product descriptions into the AI's training data via [Data Sources](https://platform.open.cx/data-sources). This is a separate setup from the store connection above.

    <Card title="Set up Knowledge Base Sync" icon="book" href="/knowledge/sources/shopify/connect">
      OAuth connect, stream selection, and sync schedule.
    </Card>
  </Tab>
</Tabs>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Store" icon="plug" href="/integrations/shopify/connect">
    Custom app, scopes, token, and domain setup.
  </Card>

  <Card title="AI Actions" icon="robot" href="/integrations/shopify/ai-actions">
    Order lookup, product search, and shop details.
  </Card>

  <Card title="Knowledge Base Sync" icon="book" href="/knowledge/sources/shopify/connect">
    Train the AI on your store pages, articles, and products.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/shopify/troubleshooting">
    Connection issues, missing orders, search relevance.
  </Card>
</CardGroup>


# Shopify troubleshooting
Source: https://docs.open.cx/integrations/shopify/troubleshooting

Debug Shopify connection errors, missing orders, search relevance, and inbox metadata issues.

Before debugging, have this ready:

* Your Shopify `*.myshopify.com` domain.
* The scopes you configured on the custom app (`read_orders`, `read_products`, `read_customers`).
* A specific order number or customer email where the problem shows.

<Tip>
  Go to [**Settings → Integrations**](https://platform.open.cx/settings/integrations) → Shopify as your first step. If the connection is not listed or shows an error, re-enter your credentials.
</Tip>

## Common scenarios

Jump to the symptom that matches what you're seeing.

### **Connection fails on save**

<Tooltip>Likely cause</Tooltip>: wrong domain format or invalid token.

**Fix:**

* Use the `*.myshopify.com` domain, not your custom storefront domain (e.g. `example.myshopify.com`, not `www.example.com`).
* If you already revealed the token and lost it, go to your Shopify admin, uninstall the custom app, reinstall it, and reveal a new token.
* Confirm the app has `read_orders`, `read_products`, and `read_customers` scopes enabled. OpenCX checks scopes on save and rejects the connection if any are missing.

### **AI doesn't return order details**

<Tooltip>Likely cause</Tooltip>: order is archived or email mismatch.

**Fix:**

* **Auto-archival:** in your Shopify admin, go to **Settings → General → Order processing** and confirm **Automatically archive the order** is unchecked. Archived orders are not returned by the Shopify API. If you recently disabled auto-archival, previously archived orders remain archived — you need to unarchive them manually in Shopify.
* **Email mismatch:** the AI verifies the customer's email against the order before revealing details. If the contact in OpenCX has a different email than the one on the Shopify order, the lookup is rejected. Confirm the contact's email matches.
* **Order number format:** the customer must provide the order number as it appears in Shopify (e.g. `#1042` or `1042`). Custom prefixes like `UK-1042` work if that is the order name in Shopify.

### **Product search returns irrelevant results**

<Tooltip>Likely cause</Tooltip>: keyword mismatch between the customer's question and your product data.

**Fix:**

* The AI searches your catalog using Shopify's native keyword search. If products have generic titles or sparse descriptions, searches for specific attributes (color, material, size) may not match.
* Improve product titles and descriptions in Shopify to include the terms customers actually use.
* Results are sorted by relevance and capped to avoid overwhelming the AI with data. If a product ranks outside the top results, it may not appear.

### **Customer metadata not showing in the inbox sidebar**

<Tooltip>Likely cause</Tooltip>: missing scope or no email match.

**Fix:**

* Confirm the custom app has the `read_customers` scope. Without it, metadata enrichment is disabled entirely.
* Confirm the contact in OpenCX has an email address set.
* Confirm a customer with that exact email exists in your Shopify store. The match is exact — `john@example.com` does not match `John@Example.com` if Shopify stored it differently.
* If you recently connected the store, try refreshing the inbox page. Metadata loads on sidebar open.

### **Knowledge base content not appearing in AI answers**

<Tooltip>Likely cause</Tooltip>: sync incomplete or scope mismatch.

**Fix:**

* Open [**AI Training → Data Sources**](https://platform.open.cx/data-sources) and check the Shopify source status. If it shows **Syncing**, wait for it to complete.
* Verify that the custom app used for Knowledge Sync has the scopes matching your selected streams: `read_online_store_pages` for pages, `read_content` for articles, `read_products` for products.
* If scopes were missing, update them in the Shopify admin, then disconnect and reconnect the source in OpenCX.

### **Multi-store: AI looks up the wrong store**

<Tooltip>Likely cause</Tooltip>: no clear signal for the AI to distinguish stores.

**Fix:**

* Use **order number prefixes** per store (e.g. `UK-`, `DE-`, `NL-`) so the AI can route by the prefix. Configure in Shopify admin under **Settings → General → Order processing**.
* Train the AI with store-specific instructions that explain which store serves which region or product line.
* Confirm each store has a distinct `*.myshopify.com` domain configured in OpenCX — duplicate domains will cause conflicts.

### **None of the above**

If your issue isn't listed here, contact support with:

* Your OpenCX organization name.
* The Shopify domain(s) involved.
* A specific session ID or order number where the problem occurred.
* Screenshots of any error messages.

## Limits and timing

| | Value |
| - | - |
| **Contact metadata cache** | 1 minute |
| **Orders loaded per customer** | Up to 50 per store |
| **Knowledge Base initial sync** | Minutes to an hour depending on content volume |
| **Knowledge Base incremental sync** | Scheduled (configurable per source) |
| **Product search results** | Capped to prevent noisy data in AI context |

***

## Related Documentation

<CardGroup>
  <Card title="Connect Store" icon="plug" href="/integrations/shopify/connect">
    Re-check credentials, scopes, and domain format.
  </Card>

  <Card title="AI Actions" icon="robot" href="/integrations/shopify/ai-actions">
    Confirm the right actions are enabled.
  </Card>

  <Card title="Knowledge Base Sync" icon="book" href="/knowledge/sources/shopify/connect">
    Re-check OAuth credentials and stream selection.
  </Card>

  <Card title="Handoff settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# SMS in Twilio Flex
Source: https://docs.open.cx/integrations/twilio-flex/channels/sms

Route AI SMS conversations into Flex as messaging tasks so reps reply from the Flex UI to the contact's phone.

Inbound SMS conversations route through the Flex Conversations service as messaging tasks. When the AI hands off, your rep replies from the Flex UI and the reply lands on the contact's phone as an SMS.

## Pre-requisites

<Warning>
  **Set up AI SMS first.** Flex SMS handoff depends on AI SMS being wired up end-to-end — start with [AI SMS Support](/sms/introduction) and come back here.
</Warning>

* **AI SMS configured and receiving messages** — see [AI SMS Support](/sms/introduction).
* **Twilio Flex credentials saved** — see [Connect Twilio Flex](/integrations/twilio-flex/connect).
* **Both webhooks registered** (TaskRouter + Conversations service).

## How messages land in Flex

```mermaid theme={"dark"}
flowchart LR
  A[Contact texts number] --> B[AI replies]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation closes]
  C -- No --> E[Handoff attribute set on task]
  E --> F[Workflow routes to human queue]
  F --> G[Rep replies from Flex]
```

## What the rep sees

* A **messaging task** in the Flex UI with the contact's phone number as the subject.
* The full AI-to-contact SMS transcript in the conversation thread.
* The handoff note above the transcript with summary, sentiment, and reason.
* The six `handoff*` attributes on the task panel.
* Any `flex_*` custom data the workflow set during routing.
* Replies typed in the Flex UI send as SMS to the contact's number.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Opt-out keywords" icon="ban">
    Twilio's default opt-out keywords (`STOP`, `UNSUBSCRIBE`, etc.) are handled upstream by your carrier — the OpenCX AI never sees a message from an opted-out number, and no Flex task is created.
  </Accordion>

  <Accordion title="10DLC and toll-free rules still apply" icon="flag">
    Flex SMS inherits the same <Tooltip href="/sms/compliance">10DLC</Tooltip> or toll-free verification rules as any other Twilio SMS integration. OpenCX does not add or waive those — fix any registration issues with Twilio.
  </Accordion>

  <Accordion title="Session matching by phone number" icon="fingerprint">
    OpenCX matches an inbound SMS to an existing session by the contact's phone number. A new number is a new session; an existing number continues the last session until it closes.
  </Accordion>

  <Accordion title="MMS behavior" icon="image">
    MMS attachments flow through to the Flex conversation as media attachments. Reps can view them inline and reply with their own attachments; MMS quotas and size limits follow your Twilio plan.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI SMS Support" icon="comment-sms" href="/sms/introduction">
    The channel itself — numbers, routing, compliance.
  </Card>

  <Card title="Connect Twilio Flex" icon="plug" href="/integrations/twilio-flex/connect">
    Credentials, webhook, workflow filters.
  </Card>

  <Card title="Twilio Flex overview" icon="headset" href="/integrations/twilio-flex/overview">
    What else Flex lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/twilio-flex/troubleshooting">
    Missing task, wrong queue, events routed to the wrong org.
  </Card>
</CardGroup>


# Voice in Twilio Flex
Source: https://docs.open.cx/integrations/twilio-flex/channels/voice

Route AI Phone calls into Flex as voice tasks with transcript attached so reps pick up mid-call with full context.

Voice calls handled by AI Phone route as <Tooltip>voice tasks</Tooltip> in Flex. When the AI escalates mid-call, the call transfers to your rep with the transcript already attached.

## Pre-requisites

<Warning>
  **Set up AI Phone first.** Flex voice handoff depends on AI Phone being wired up end-to-end — start with [AI Phone Support](/phone/introduction) and come back here.
</Warning>

* **AI Phone configured and receiving calls** — see [AI Phone Support](/phone/introduction).
* **Twilio Flex credentials saved** — see [Connect Twilio Flex](/integrations/twilio-flex/connect).
* **Both webhooks registered** (TaskRouter + Conversations service).

## How calls land in Flex

```mermaid theme={"dark"}
flowchart LR
  A[Caller dials number] --> B[AI picks up]
  B --> C{AI can resolve?}
  C -- Yes --> D[Caller hangs up]
  C -- No --> E[Handoff attribute set on task]
  E --> F[Workflow routes to human queue]
  F --> G[Call transfers to rep]
```

## What the rep sees

* A **voice task** in the Flex UI with the call already connected on accept.
* The call transcript so far, rendered in the conversation thread attached to the task.
* The handoff note above the transcript with summary, sentiment, and reason.
* The six `handoff*` attributes on the task panel.
* Caller number, any `flex_*` custom data set during routing.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Warm transfer vs cold handoff" icon="arrow-right-arrow-left">
    OpenCX performs a cold handoff by default — the AI releases the call and your workflow routes it to a human queue. For warm transfers (AI introduces the rep on the line before dropping off), configure it inside your Flex workflow; OpenCX does not orchestrate warm-transfer TwiML on your behalf.
  </Accordion>

  <Accordion title="Transcript timing" icon="clock">
    The transcript is appended to the conversation as the AI and caller speak. On handoff, the most recent turns are guaranteed to be present; occasional sub-second tail segments may land a moment after the task is assigned.
  </Accordion>

  <Accordion title="Call recording" icon="circle-dot">
    Call recordings follow whatever your Twilio Voice configuration sets — OpenCX does not add or strip recording. If you rely on Twilio recordings for QA, the recording SID is on the call, not on the task.
  </Accordion>

  <Accordion title="IVR skip-ahead" icon="forward">
    If your number routes through an IVR before reaching the AI, OpenCX only sees the portion of the call after it picks up. Earlier IVR selections are not in the transcript unless your IVR passes them as task attributes.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Phone Support" icon="phone" href="/phone/introduction">
    The channel itself — numbers, IVR, voice model.
  </Card>

  <Card title="Connect Twilio Flex" icon="plug" href="/integrations/twilio-flex/connect">
    Credentials, webhook, workflow filters.
  </Card>

  <Card title="Twilio Flex overview" icon="headset" href="/integrations/twilio-flex/overview">
    What else Flex lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/twilio-flex/troubleshooting">
    Missing task, wrong queue, events routed to the wrong org.
  </Card>
</CardGroup>


# Web Chat in Twilio Flex
Source: https://docs.open.cx/integrations/twilio-flex/channels/web-chat

Route AI Chat Widget conversations into Flex tasks so reps pick up live chats in the Flex UI with full AI context.

Web chat conversations from the AI Chat Widget route through the <Tooltip>Flex Conversations service</Tooltip>. When the AI hands off, your rep picks it up as a live messaging task in Flex — no ticket, no context lost.

## Pre-requisites

<Warning>
  **Install the AI Chat Widget on your site first.** Flex has nothing to route until the widget is live — start with [Install Widget](/widget/install-widget) and come back here.
</Warning>

* **Widget installed and reachable** — see [Install Widget](/widget/install-widget).
* **Twilio Flex credentials saved** — see [Connect Twilio Flex](/integrations/twilio-flex/connect).
* **Both webhooks registered** (TaskRouter + Conversations service).

## How conversations land in Flex

```mermaid theme={"dark"}
flowchart LR
  A[Visitor opens widget] --> B[AI answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Visitor closes the chat]
  C -- No --> E[Handoff attribute set on task]
  E --> F[Workflow routes to human queue]
  F --> G[Rep picks up task in Flex]
```

## What the rep sees

* A **messaging task** in the Flex UI assigned to their queue.
* The full AI-to-visitor transcript in the conversation thread.
* The handoff note at the top with summary, sentiment, and reason.
* The six `handoff*` attributes on the task panel (see [Handoff](/integrations/twilio-flex/handoff#what-opencx-writes-to-the-task)).
* Any `flex_*` custom data the workflow set during routing.
* Replies typed in the Flex UI land back in the visitor's widget within a couple of seconds.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Authenticated visitors vs anonymous visitors" icon="shield-check">
    When the widget passes a verified identity via [widget authentication](/widget/authentication), OpenCX attaches the verified email and contact ID to the Flex conversation. Anonymous visitors show up as a fresh contact until they identify themselves.
  </Accordion>

  <Accordion title="Files visitors upload" icon="paperclip">
    Files uploaded in the widget appear as attachments on the Flex conversation. File-size limits follow your Twilio Conversations plan.
  </Accordion>

  <Accordion title="CSAT after the chat ends" icon="star">
    If your workflow triggers <Tooltip>CSAT</Tooltip>, the rating lands on the OpenCX session, not on the Flex task. Find it via the session ID in the [Inbox](https://platform.open.cx/inbox).
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Chat Widget" icon="messages" href="/widget/introduction">
    The channel itself — install, configure, authenticate.
  </Card>

  <Card title="Connect Twilio Flex" icon="plug" href="/integrations/twilio-flex/connect">
    Credentials, webhook, workflow filters.
  </Card>

  <Card title="Twilio Flex overview" icon="headset" href="/integrations/twilio-flex/overview">
    What else Flex lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/twilio-flex/troubleshooting">
    Missing task, wrong queue, events routed to the wrong org.
  </Card>
</CardGroup>


# WhatsApp in Twilio Flex
Source: https://docs.open.cx/integrations/twilio-flex/channels/whatsapp

Route AI WhatsApp conversations into Flex as messaging tasks with the full transcript and contact profile attached.

WhatsApp conversations route through the Flex Conversations service as messaging tasks. When the AI hands off, your rep replies from the Flex UI and the reply lands on the contact's WhatsApp thread.

## Pre-requisites

<Warning>
  **Set up AI WhatsApp first.** Flex WhatsApp handoff depends on AI WhatsApp being wired up end-to-end — start with [AI WhatsApp Support](/whatsapp/introduction) and come back here.
</Warning>

* **AI WhatsApp configured and receiving messages** — see [AI WhatsApp Support](/whatsapp/introduction).
* **Twilio Flex credentials saved** — see [Connect Twilio Flex](/integrations/twilio-flex/connect).
* **Both webhooks registered** (TaskRouter + Conversations service).

## How messages land in Flex

```mermaid theme={"dark"}
flowchart LR
  A[Contact messages WhatsApp] --> B[AI replies]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation closes]
  C -- No --> E[Handoff attribute set on task]
  E --> F[Workflow routes to human queue]
  F --> G[Rep replies from Flex]
```

## What the rep sees

* A **messaging task** in the Flex UI with the contact's WhatsApp profile name and number.
* The full AI-to-contact transcript in the conversation thread.
* The handoff note above the transcript with summary, sentiment, and reason.
* The six `handoff*` attributes on the task panel.
* Any `flex_*` custom data the workflow set during routing.
* Replies typed in the Flex UI send to the contact's WhatsApp.

## Channel-specific details

<AccordionGroup>
  <Accordion title="24-hour session window" icon="clock">
    WhatsApp's <Tooltip>24-hour customer care window</Tooltip> applies. If your rep tries to reply outside the window, WhatsApp rejects the message unless it matches an approved template.
  </Accordion>

  <Accordion title="Template messages outside the window" icon="file-lines">
    To reach a contact outside the 24-hour window, reps must send an approved WhatsApp template. Template approval and variables happen in your WhatsApp Business account — not in OpenCX or Flex.
  </Accordion>

  <Accordion title="Media attachments" icon="paperclip">
    Images, documents, and audio sent by the contact appear on the Flex conversation as attachments. Size limits follow WhatsApp's per-media-type limits.
  </Accordion>

  <Accordion title="Contact profile name mapping" icon="id-card">
    The name on the task is pulled from the contact's WhatsApp profile. If the contact's profile name changes later, Flex won't retroactively update existing tasks — new tasks pick up the new name.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI WhatsApp Support" icon="whatsapp" href="/whatsapp/introduction">
    The channel itself — numbers, templates, profile setup.
  </Card>

  <Card title="Connect Twilio Flex" icon="plug" href="/integrations/twilio-flex/connect">
    Credentials, webhook, workflow filters.
  </Card>

  <Card title="Twilio Flex overview" icon="headset" href="/integrations/twilio-flex/overview">
    What else Flex lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/twilio-flex/troubleshooting">
    Missing task, wrong queue, events routed to the wrong org.
  </Card>
</CardGroup>


# Connect Twilio Flex
Source: https://docs.open.cx/integrations/twilio-flex/connect

Save Flex credentials, copy the org-scoped webhook URL, and register it on both TaskRouter and the Conversations service.

Connecting Flex is three pieces of work: paste credentials, register the webhook on both Twilio surfaces, and add two workflow filters. Miss any one and handoff looks silently broken.

<TwilioFlexFlow />

<Warning>
  **The webhook URL is scoped to a single OpenCX org and environment.** Do not
  reuse a sandbox webhook URL against a production Twilio account — the token in
  the URL carries your `orgId`, so events will silently route to the wrong
  workspace. Copy the URL fresh from every environment you're connecting.
</Warning>

## Before you start

<AccordionGroup>
  <Accordion title="Flex admin access" icon="user-shield">
    You need access to the <Tooltip>Twilio Flex Console</Tooltip> and the parent Twilio Console to copy credentials and register webhooks.
  </Accordion>

  <Accordion title="Workspace and AI queue ready" icon="list-check">
    Know the

    <Tooltip>
      Workspace SID
    </Tooltip>

    (starts with `WS`) you want OpenCX to join. If you have a dedicated

    <Tooltip>
      AI queue
    </Tooltip>

    , have its SID handy too.
  </Accordion>

  <Accordion title="A workflow you can edit" icon="diagram-project">
    You need edit access to the <Tooltip>TaskRouter workflow</Tooltip> that routes your inbound tasks — you'll add two filters to it before the setup is complete.
  </Accordion>
</AccordionGroup>

## Save credentials in OpenCX

<Steps>
  <Step title="Open the Flex integration">
    Go to [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard and click **Twilio Flex**.
  </Step>

  <Step title="Paste credentials">
    Fill in the form:

    | Field | Where to find it |
    | - | - |
    | **Account SID** | Twilio Console dashboard — starts with `AC`. |
    | **Auth Token** | Twilio Console dashboard — account-level token. |
    | **Workspace SID** | Flex Console → Configuration → Workspace — starts with `WS`. |
    | **AI Queue SID** *(optional)* | Flex Console → TaskRouter → Queues — starts with `WQ`. Leave blank to skip queue filtering. |
    | **AI Worker Email Domain** *(optional)* | Your own domain, e.g. `yourcompany.com`. Each AI worker's Twilio attributes then include an email like `opencx1-a1b2c3d4@yourcompany.com`. Set it only if a downstream system reads worker emails; leave empty otherwise. |

    <Note>
      OpenCX automatically provisions an <Tooltip>AI worker</Tooltip> in your workspace on first save — you do **not** create this worker yourself. Its SID is persisted inside OpenCX so your workflow filter can target it. Saving again later never creates extra workers.
    </Note>
  </Step>

  <Step title="Optional: scale the AI worker pool">
    Twilio caps each worker at **50 concurrent chats**. If you expect more
    parallel conversations, use the **AI Agents** section in the integration
    settings and click **Add AI Agent** — each worker you add raises total
    capacity by 50 (2 workers = 100 concurrent chats, and so on). Every pool
    worker carries the same `ai` and `support` routing skills, so your workflow
    filter matches all of them without changes.
  </Step>

  <Step title="Copy the webhook URL">
    The **Webhook URL** field at the top of the modal shows the URL OpenCX will
    accept events on. Copy it — you'll paste it into Twilio twice.
  </Step>

  <Step title="Click Test & Save">
    OpenCX validates the credentials against TaskRouter's workspace API. A failure means the Account SID, Auth Token, or Workspace SID is wrong.
  </Step>
</Steps>

## Register the webhook on TaskRouter

In the Twilio Flex Console, open **TaskRouter → Workspaces → \[your workspace] → Event Callbacks**. Paste the OpenCX webhook URL and subscribe to the following events:

<Tabs>
  <Tab title="TaskRouter events">
    Subscribe this URL to **all** of these events:

    * `reservation.created`
    * `reservation.accepted`
    * `reservation.timeout`
    * `task.created`
    * `workflow.target-matched`

    Save. TaskRouter will start delivering events immediately.
  </Tab>
</Tabs>

## Register the webhook on the Conversations service

In the Twilio Console, open **Conversations → Services → \[your Flex Conversations service] → Webhooks**. Paste the **same** OpenCX webhook URL and subscribe to:

<Tabs>
  <Tab title="Conversations filters">
    Subscribe this URL to **all** of these filters:

    * `onMessageAdded`
    * `onConversationAdded`
    * `onParticipantAdded`

    Save.
  </Tab>
</Tabs>

<Warning>
  **Both webhooks are required.** Registering only the TaskRouter webhook is the
  single most common onboarding mistake — customer messages reach OpenCX but no
  task is created, because the Conversations events never arrive. Register both
  before moving on.
</Warning>

## Add the workflow filters

Open your TaskRouter workflow and add two filters, in this order:

<Steps>
  <Step title="Route AI-skilled tasks to the OpenCX AI worker">
    If you set an **AI Queue SID** during credentials, filter on that queue. Otherwise, filter on the routing skills `ai` and `support` — OpenCX adds both to every AI worker it provisions, so one filter covers the whole pool. This is the filter that gets the AI a crack at the task first.
  </Step>

  <Step title="Route `handedOff == true` tasks to your human queue">
    Filter expression: `handedOff == true`. Target your human agent queue (support, tier 2, etc.). This is the filter OpenCX relies on after it rejects the AI reservation — without it, a handed-off task sits in limbo.
  </Step>
</Steps>

## Verify end to end

<Steps>
  <Step title="Send a test message">
    Send a message on the channel you wired up (SMS, WhatsApp, web chat, voice call). OpenCX's AI worker should accept the reservation and reply.
  </Step>

  <Step title="Check the task in Flex">
    Open TaskRouter → Tasks. The task should show the AI worker as the assigned
    worker, with `conversationSid` present in the task attributes.
  </Step>

  <Step title="Trigger a handoff">
    Reply with *"I want to talk to a human"* (or whatever handoff trigger your org uses). The task should re-route — check the attributes for `handedOff: true` and the reason/summary fields. Your human queue should now own the task.
  </Step>
</Steps>

<Tip>
  If the AI never accepts, your workflow filter isn't matching the AI worker. If
  the AI accepts but handoff never re-routes, the `handedOff == true` filter is
  missing. See [Troubleshooting](/integrations/twilio-flex/troubleshooting).
</Tip>

***

## Related Documentation

<CardGroup>
  <Card title="Handoff and task attributes" icon="user-group" href="/integrations/twilio-flex/handoff">
    What OpenCX writes to every task on handoff.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/twilio-flex/channels/web-chat">
    Per-channel implementation on top of this shared setup.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/twilio-flex/troubleshooting">
    Missing webhook, wrong queue, events routed to the wrong org.
  </Card>

  <Card title="Human handoff" icon="user-headset" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Handoff and task attributes
Source: https://docs.open.cx/integrations/twilio-flex/handoff

What OpenCX writes to Flex when the AI escalates, how the AI worker fits into your TaskRouter workflow, and who closes Flex tasks.

OpenCX does not replace your TaskRouter workflow — it participates in it as one more worker. This page describes exactly what OpenCX writes to a Flex task on handoff, what your workflow is expected to do with it, and the one thing OpenCX explicitly does **not** do (close the task).

## How handoff works

```mermaid theme={"dark"}
flowchart LR
  A[AI is on the task] --> B{AI can resolve?}
  B -- Yes --> C[AI replies, task stays]
  B -- No --> D[Update task attributes]
  D --> E[Reject AI reservation]
  E --> F[Workflow matches handedOff == true]
  F --> G[Rep picks up from human queue]
  G --> H[Handoff note posted in conversation]
```

When a handoff fires, OpenCX runs these steps in order:

<Steps>
  <Step title="Update the Flex task attributes">
    OpenCX writes the handoff fields (see the table below) into the task's `attributes` JSON via TaskRouter's API. Any attributes your workflow already set on the task are preserved.
  </Step>

  <Step title="Reject the AI reservation">
    The <Tooltip>AI reservation</Tooltip> is rejected. The task is now eligible for re-routing.
  </Step>

  <Step title="Workflow re-routes">
    TaskRouter re-evaluates the task against your workflow filters. The `handedOff == true` filter matches, and the task is assigned to your human queue.
  </Step>

  <Step title="Handoff note posts to the conversation">
    OpenCX posts a short system message into the Flex conversation with the summary, sentiment, and reason, so the rep who picks up sees it above their first reply.
  </Step>
</Steps>

## What OpenCX writes to the task

| Attribute | Type | Purpose |
| - | - | - |
| `handedOff` | boolean | Always `true`. The filter your workflow keys on. |
| `handoffReason` | string | Short phrase the AI wrote when escalating — e.g. *"customer wants to cancel subscription"*. |
| `handoffSummary` | string | One-paragraph summary of the conversation so far. |
| `handoffSentiment` | string | Detected sentiment — `positive`, `neutral`, or `negative`. |
| `handoffLanguage` | string | BCP-47 language code of the conversation — e.g. `en`, `es`, `ar`. |
| `handoffTimestamp` | ISO 8601 string | When the handoff fired. |

<Note>
  OpenCX only adds these attributes. Every other attribute on the task — whatever your workflow set during routing — stays untouched.
</Note>

## What the rep sees in Flex

* The task in their queue with the six handoff attributes above, visible in the **Task** panel of the Flex UI.
* A system message at the top of the Flex conversation thread: the summary, sentiment, and reason formatted for human reading.
* The full <Tooltip>customer transcript</Tooltip> above the handoff note — no replay, no separate tab.
* Any `flex_*` custom data the workflow set during routing (see below) preserved on the task.

The AI's replies appear in the conversation as author `AI Support Agent`, so the rep can distinguish them from the customer's own messages.

## Using Flex attributes in Autopilot

Every attribute your Flex workflow attaches to a task is flattened onto the OpenCX session's `custom_data` with a `flex_` prefix. Autopilot actions read from `custom_data` directly — no extra mapping.

<AccordionGroup>
  <Accordion title="Flattening rule" icon="code">
    A Flex attribute named `order_id` becomes `flex_order_id` on the session. Nested attributes are flattened with underscores — `customer.name` becomes `flex_customer_name`. The flattening happens on every task event, so late-arriving attributes show up without you re-running anything.
  </Accordion>

  <Accordion title="Typical attributes worth routing on" icon="sliders">
    Teams commonly set `order_id`, `user_id`, `city`, `zone`, or tier tags on the task. Any of these show up as `flex_order_id`, `flex_user_id`, etc., and can be used in an <Tooltip href="/handoff/topics">Autopilot condition</Tooltip>.
  </Accordion>

  <Accordion title="Naming comes from your workflow" icon="fingerprint">
    OpenCX does not define which attributes exist — your Flex workflow does. The only guarantee is the `flex_` prefix. If you rename an attribute on the Flex side, update your Autopilot conditions to match.
  </Accordion>
</AccordionGroup>

## Closing Flex tasks

<Warning>
  **OpenCX does not close Flex tasks.** When the AI resolves or hands off, OpenCX only marks its own session state and rejects the reservation — it never calls `task.complete()` or sets `assignmentStatus: 'completed'`. Closing the Flex task is your rep's or your workflow's responsibility.
</Warning>

If you want tasks to close automatically on AI resolution:

* Add a TaskRouter event callback on `task.wrapup` or `reservation.wrapup` and close via your own automation.
* Or configure a Flex workflow rule that closes tasks whose AI reservation was rejected without a successor assignment — depending on how your queues are structured.

Treat this as product parity with your existing Flex task lifecycle, not as something OpenCX overrides.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Twilio Flex" icon="plug" href="/integrations/twilio-flex/connect">
    Credentials, webhook registration, workflow filters.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/twilio-flex/channels/web-chat">
    Per-channel implementation on top of this shared setup.
  </Card>

  <Card title="Autopilot topics" icon="sliders" href="/handoff/topics">
    Read `flex_*` custom\_data in topic conditions and actions.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/twilio-flex/troubleshooting">
    Handoff fires but the task stays in the AI queue, and other scenarios.
  </Card>
</CardGroup>


# Twilio Flex overview
Source: https://docs.open.cx/integrations/twilio-flex/overview

Run Twilio Flex as your contact center while OpenCX resolves what it can, escalates what it can''t, and writes every handoff back into the Flex task your reps already own.

OpenCX works alongside your reps inside Twilio Flex. The AI resolves what it can, escalates what it can't, and when a task reaches a human it arrives in <Tooltip>TaskRouter</Tooltip> with the full summary, sentiment, and reason already attached — no context rebuild, no separate inbox.

<Tip>
  Setup starts at [**Settings →
  Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX
  dashboard.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="AI deflects before a rep ever sees the task" icon="robot">
    OpenCX accepts the <Tooltip>reservation</Tooltip> on behalf of an automatically provisioned AI worker and replies instantly in the same Flex conversation your reps use. If the AI resolves, the task never surfaces to a human queue. Each AI worker handles up to 50 concurrent chats (a Twilio per-worker cap) — add more workers to the pool from the integration settings to scale beyond it.
  </Accordion>

  <Accordion title="Tasks arrive with summary, sentiment, and reason" icon="ticket">
    When the AI escalates, OpenCX rejects its reservation and updates the Flex
    task attributes with `handedOff: true`, a one-paragraph summary, the reason
    for handoff, the detected sentiment, and the conversation language. Your
    workflow filter on `handedOff == true` routes it to the right human queue.
  </Accordion>

  <Accordion title="One conversation from first message to close" icon="reply">
    AI replies post into the same Flex

    <Tooltip>
      Conversations service
    </Tooltip>

    thread your rep will inherit. No copy-pasting, no duplicated identity — the
    rep picks up the handoff note and keeps going.
  </Accordion>

  <Accordion title="Flex task attributes usable in Autopilot" icon="sliders">
    Every attribute your Flex workflow sets on a task — order ID, user ID, city,
    zone — is flattened onto the OpenCX session as `flex_*` fields.

    <Tooltip href="/handoff/topics">
      Autopilot
    </Tooltip>

    actions can read them straight out of `custom_data`.
  </Accordion>

  <Accordion title="Consistent logging across every task" icon="fingerprint">
    OpenCX persists the Flex task SID, reservation SID, and conversation SID on every session, so any task in Flex traces back to the exact AI reasoning in the OpenCX Inbox.
  </Accordion>
</AccordionGroup>

## Supported channels

Twilio Flex funnels every inbound channel through one Conversations + TaskRouter pipeline. Pick the channel you're wiring in first — each page covers the implementation details on top of the shared Flex setup.

<CardGroup>
  <Card title="Web Chat" icon="comments" href="/integrations/twilio-flex/channels/web-chat">
    AI Chat Widget conversations routed to reps as Flex live chats.
  </Card>

  <Card title="Voice" icon="phone" href="/integrations/twilio-flex/channels/voice">
    AI Phone calls routed as Flex voice tasks with transcript attached.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/integrations/twilio-flex/channels/sms">
    AI SMS conversations routed as Flex messaging tasks.
  </Card>

  <Card title="WhatsApp" icon="whatsapp" href="/integrations/twilio-flex/channels/whatsapp">
    AI WhatsApp conversations routed as Flex messaging tasks.
  </Card>
</CardGroup>

## Observability

Every conversation OpenCX hands to Flex is traceable in both directions. Reps read the AI's work on the Flex task; admins trace a Flex task back to the exact OpenCX session.

<AccordionGroup>
  <Accordion title="Task and conversation IDs on every session" icon="fingerprint">
    OpenCX stores the Flex `task SID`, `reservation SID`, and `conversation SID` on the session. Search the [Inbox](https://platform.open.cx/inbox) by any of them to open the session that produced the task.
  </Accordion>

  <Accordion title="Handoff summary and sentiment on task attributes" icon="pen">
    On handoff, OpenCX writes `handedOff`, `handoffReason`, `handoffSummary`,
    `handoffSentiment`, `handoffLanguage`, and `handoffTimestamp` into the Flex
    task's attributes. Your workflow filter reads them; your rep sees them in the
    task panel.
  </Accordion>

  <Accordion title="`flex_*` fields on OpenCX `custom_data`" icon="database">
    Every attribute your Flex workflow sets on a task is flattened onto `session.custom_data` as `flex_<attribute_name>` — e.g. `flex_order_id`, `flex_user_id`, `flex_customer_name`. Usable in [Autopilot](/handoff/topics) actions without extra configuration.
  </Accordion>

  <Accordion title="Handoff note visible to the rep in Flex" icon="note-sticky">
    At handoff, OpenCX posts a system note into the Flex conversation containing the summary, sentiment, and reason. Your rep sees it inline above their first reply — no tab switching.
  </Accordion>
</AccordionGroup>

## Setup path

<Steps>
  <Step title="Connect credentials">
    Paste your Account SID, Auth Token, Workspace SID, and AI Queue SID. Copy
    the webhook URL OpenCX generates.
  </Step>

  <Step title="Register the webhook on both Twilio surfaces">
    TaskRouter **and** the Conversations service. Skipping one is the most
    common onboarding failure — see [Connect Twilio
    Flex](/integrations/twilio-flex/connect).
  </Step>

  <Step title="Add the workflow filters">
    Route AI-skilled tasks to the OpenCX AI worker; route `handedOff == true`
    tasks to your human queue.
  </Step>

  <Step title="Understand the handoff contract">
    Read [Handoff and task attributes](/integrations/twilio-flex/handoff) so you
    know exactly what OpenCX writes and what your workflow is expected to do.
  </Step>
</Steps>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Twilio Flex" icon="plug" href="/integrations/twilio-flex/connect">
    Credentials, dual webhook registration, workflow filters.
  </Card>

  <Card title="Handoff and task attributes" icon="user-group" href="/integrations/twilio-flex/handoff">
    The AI worker, task-attribute contract, closing Flex tasks.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/twilio-flex/channels/web-chat">
    Per-channel implementation details on top of the shared setup.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/twilio-flex/troubleshooting">
    Missing webhook, wrong queue, events routed to the wrong org.
  </Card>
</CardGroup>


# Twilio Flex troubleshooting
Source: https://docs.open.cx/integrations/twilio-flex/troubleshooting

Debug Flex credential errors, missing webhooks, tasks landing in the wrong queue, and duplicate messaging.

Before debugging, have this ready:

* Your Twilio <Tooltip>Account SID</Tooltip> and the Flex <Tooltip>Workspace SID</Tooltip>.
* A specific OpenCX session ID (from [Inbox](https://platform.open.cx/inbox)) or the Flex task SID where the problem shows.
* The webhook URL shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Twilio Flex.

<Tip>
  Re-run **Test & Save** in [Settings →
  Integrations](https://platform.open.cx/settings/integrations) → Twilio Flex as
  your first step. Most issues are credential or webhook related.
</Tip>

<Info>
  **Fastest path to root cause:** search the
  [Inbox](https://platform.open.cx/inbox) by the `flex_task_sid`,
  `flex_conversation_sid`, or `flex_reservation_sid` stored on the OpenCX
  session. That opens the full AI reasoning and handoff event — far faster than
  trawling Twilio's event log.
</Info>

## Common scenarios

Jump to the symptom that matches what you're seeing.

### **"Failed to verify credentials" on save**

<Tooltip>
  Likely cause
</Tooltip>

: wrong Workspace SID, or account-level Auth Token mismatch.

**Fix:** re-copy the Account SID and Auth Token from the [Twilio Console](https://console.twilio.com) dashboard. Re-copy the Workspace SID from **Flex Console → Configuration → Workspace**. Confirm they belong to the same Twilio account.

### **Handoff runs but the task stays in the AI queue**

<Tooltip>
  Likely cause
</Tooltip>

: missing `handedOff == true` workflow filter.

**Fix:** open your TaskRouter workflow and add a filter with expression `handedOff == true` targeting your human queue. Place it **before** the AI filter so a handed-off task matches humans first. Re-run a test handoff.

### **Customer messages reach OpenCX but no Flex task is created**

<Tooltip>
  Likely cause
</Tooltip>

: only the TaskRouter webhook is registered; the Conversations service webhook
is missing.

**Fix:** in the Twilio Console, open **Conversations → Services → \[your Flex Conversations service] → Webhooks**. Paste the same OpenCX webhook URL and subscribe to `onMessageAdded`, `onConversationAdded`, and `onParticipantAdded`. Both webhooks must be registered.

### **Events routed to the wrong org**

<Tooltip>
  Likely cause
</Tooltip>

: a sandbox webhook URL was pasted into a production Twilio account.

**Fix:** copy the webhook URL **freshly** from each environment's [Settings → Integrations](https://platform.open.cx/settings/integrations) → Twilio Flex page. Never copy one environment's URL into another. Update the URL on both TaskRouter and the Conversations service.

### **None of the above**

Open a support request with the Flex task SID, the OpenCX session ID (if any), and a timestamp.

## Limits and best-effort behavior

| | Value |
| - | - |
| **Duplicate message dedup window** | 1 hour (hash of conversation SID + body + send timestamp) |
| **Outbound send** | Best-effort — retries on transient Twilio failures; does not block handoff on send failure |
| **Flex task closure** | Customer-side — OpenCX never calls `task.complete()` |
| **AI worker provisioning** | Automatic on first settings save; persists until you delete it in Flex. Scale with **Add AI Agent** in the integration settings |
| **Concurrent chats per AI worker** | 50 (Twilio per-worker cap) — total capacity = workers in the pool × 50 |

<Note>
  OpenCX retries on transient Twilio failures but does not indefinitely retry
  past rate limits. If your Twilio account hits its per-minute cap, expect
  intermittent late deliveries until the window resets.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Connect Twilio Flex" icon="plug" href="/integrations/twilio-flex/connect">
    Re-verify credentials, webhooks, and workflow filters.
  </Card>

  <Card title="Handoff and task attributes" icon="user-group" href="/integrations/twilio-flex/handoff">
    Re-verify the task-attribute contract.
  </Card>

  <Card title="Twilio Flex overview" icon="headset" href="/integrations/twilio-flex/overview">
    What Flex lights up across every channel.
  </Card>

  <Card title="Human handoff" icon="user-headset" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# AI Email Support
Source: https://docs.open.cx/integrations/zendesk/channels/email

Create Zendesk tickets from every email handoff so your reps work them from the inbox they already live in.

Email is the one channel that routes through the [Ticketing API](/integrations/zendesk/ticketing-api) path, not Sunshine. Every email handoff creates (or appends to) a Zendesk <Tooltip>ticket</Tooltip> so your reps work email the way Zendesk is designed to handle it — tickets with SLAs, triggers, and macros.

## Pre-requisites

<Warning>
  **Set up email forwarding first.** No email handoff has anything to ticket until inbound mail is reaching OpenCX — start with [Connect Email](/email/forwarding) and come back here.
</Warning>

* **Email forwarding configured** — see [Connect Email](/email/forwarding).
* **Zendesk Ticketing API credentials, webhook, and trigger saved** — see [Ticketing API](/integrations/zendesk/ticketing-api).

## How conversations land in Zendesk

```mermaid theme={"dark"}
flowchart LR
  A[Customer emails your support address] --> B[AI replies from the same address]
  B --> C{AI can resolve?}
  C -- Yes --> D[Thread stays email-only]
  C -- No --> E[Handoff]
  E --> F[Zendesk ticket created with transcript + custom fields]
  F --> G[Rep replies publicly — lands in customer's inbox]
```

## Setting up

<Steps>
  <Step title="Confirm email forwarding works">
    Open [**Channels → AI Email**](https://platform.open.cx/channels/configure/mail) in the OpenCX dashboard. Your forwarding address should be listed and verified. Send a test email and confirm it reaches the [Inbox](https://platform.open.cx/inbox).
  </Step>

  <Step title="Confirm Zendesk Ticketing is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **Zendesk → Ticketing**. The status should show **Active** and the webhook URL should be displayed.
  </Step>

  <Step title="Confirm the Zendesk trigger is active">
    In [**Zendesk Admin Center → Triggers**](https://admin.zendesk.com/objects-rules/rules/triggers), verify the OpenCX trigger fires on `Ticket | Is | Updated` with a public comment present. See [Ticketing API setup](/integrations/zendesk/ticketing-api#create-the-trigger-that-fires-the-webhook) for the exact configuration.
  </Step>

  <Step title="Trigger a test handoff">
    Send a test email to your connected address and respond with something that causes the AI to escalate. Alternatively, go to the [Inbox](https://platform.open.cx/inbox) and manually hand off the session.
  </Step>

  <Step title="Verify the ticket in Zendesk">
    A ticket should appear in Zendesk tagged `opencx`, `opencx_handedoff`, and `opencx_channel_email`. Check:

    * The **summary** is the ticket description.
    * The **full transcript** is the first comment.
    * Any <Tooltip>custom fields</Tooltip> you mapped are pre-filled.
    * The **View session in OpenCX** link opens the right session.
  </Step>

  <Step title="Reply and verify sync">
    Post a **public** reply from Zendesk. Confirm it arrives in the customer's email and shows as an agent message in the [OpenCX Inbox](https://platform.open.cx/inbox).
  </Step>
</Steps>

## What the rep sees

* A **Zendesk ticket** tagged `opencx`, `opencx_handedoff`, and `opencx_channel_email`.
* Conversation **summary as the description**, full transcript as the first comment.
* **Custom fields pre-filled** by the AI on the fields you mapped at [Settings → Ticketing](https://platform.open.cx/settings/ticketing) → Auto fill Zendesk fields.
* **`external_id` set to the OpenCX session UUID** — filter Zendesk views by <Tooltip>`external_id`</Tooltip> to find the ticket later.
* A **View session in OpenCX** link in the first comment — one click opens the full AI reasoning, tool calls, and handoff event.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Ticket-append on returning contacts" icon="rotate">
    If the same contact re-engages before the ticket is closed, OpenCX appends to the existing ticket instead of opening a new one. Your reps keep context; your reports don't inflate.
  </Accordion>

  <Accordion title="Public reply syncs back to the customer's inbox" icon="reply">
    When your rep posts a **public** reply in Zendesk, the webhook fires and OpenCX delivers the reply to the customer's original email thread. Internal notes stay private — OpenCX fetches the comment from Zendesk and syncs only public replies, so notes never reach the customer.
  </Accordion>

  <Accordion title="Attachments" icon="paperclip">
    Attachments the customer sends by email are uploaded to Zendesk and appear on the ticket. Attachments your rep adds to a public reply sync back through the customer's email thread (subject to your email provider's attachment limits).
  </Accordion>

  <Accordion title="Create a ticket for every email, not just on handoff" icon="file-circle-plus">
    By default OpenCX creates a ticket only on handoff. If your compliance or SLA reporting requires a ticket for every email, reach out to support — this flag is set per organization.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Email Support" icon="envelope" href="/email/introduction">
    The channel itself — forwarding setup, flow, troubleshooting.
  </Card>

  <Card title="Ticketing API setup" icon="plug" href="/integrations/zendesk/ticketing-api">
    Credentials, webhook, trigger, AI Fields, tags.
  </Card>

  <Card title="Zendesk overview" icon="headset" href="/integrations/zendesk/overview">
    What else Zendesk lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/zendesk/troubleshooting">
    Tickets not created, replies not syncing, AI fields blank.
  </Card>
</CardGroup>


# AI Phone Support
Source: https://docs.open.cx/integrations/zendesk/channels/phone

Route phone conversations from OpenCX into the Zendesk Agent Workspace with full transcript and handoff context.

Phone conversations route through <Tooltip>Sunshine Conversations</Tooltip>. When the AI phone agent hands off a call, your rep picks it up as a conversation inside the Zendesk <Tooltip>Agent Workspace</Tooltip> — with the full transcript attached and a clear handoff reason.

## Pre-requisites

<Warning>
  **Create your AI Phone agent first.** No calls can hand off until the agent exists and a number is bound to it — start with [Create Phone Agent](/phone/create-agent) and come back here.
</Warning>

* **AI Phone agent created and reachable on a number** — see [Create Phone Agent](/phone/create-agent) and [Inbound calls](/phone/inbound-calls).
* **Zendesk Sunshine credentials saved** — see [Sunshine Conversations](/integrations/zendesk/sunshine-conversations).

## How conversations land in Zendesk

```mermaid theme={"dark"}
flowchart LR
  A[Caller dials your number] --> B[AI voice agent answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Call ends]
  C -- No --> E[Handoff — live transfer or logged escalation]
  E --> F[Conversation + transcript in Agent Workspace]
  F --> G[Rep follows up on the preferred channel]
```

## Setting up

<Steps>
  <Step title="Confirm the phone agent is live">
    Open [**Channels → Phone**](https://platform.open.cx/channels/phone) in the OpenCX dashboard. Your AI Phone agent should appear with an active number. Test a call to confirm the agent answers.
  </Step>

  <Step title="Confirm Sunshine is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **Zendesk → Messaging**. The status should show **Active**.
  </Step>

  <Step title="Trigger a test handoff">
    Call the agent's number and say something like *"I need to speak with a person."* The AI should hand off.
  </Step>

  <Step title="Verify in the Zendesk Agent Workspace">
    The conversation should appear with the **full call transcript** attached. Confirm it's tagged `opencx_channel_phone` and that the handoff reason summary is visible.
  </Step>
</Steps>

## What the rep sees

* A **conversation in the Agent Workspace** tagged `opencx_channel_phone`.
* The **full call transcript** (AI and caller, with timestamps) attached as messages on the conversation.
* `opencx_session_id` on the conversation <Tooltip>`metadata`</Tooltip> — the trace key to the recording and full debug view in OpenCX.
* The handoff reason (what the caller asked for, what the AI couldn't resolve) in the conversation summary.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Transcript timing" icon="clock">
    The transcript is attached at handoff time, not live during the call. Reps see the conversation appear within a few seconds of the transfer or escalation flag.
  </Accordion>

  <Accordion title="Live transfer vs logged escalation" icon="arrow-right-arrow-left">
    Two handoff modes:

    * **Live transfer** — the AI bridges the caller to a configured phone number. The caller stays on the line. A Zendesk conversation still gets created with the transcript so your rep has context.
    * **Logged escalation** — the AI ends the call and creates the Zendesk conversation for a rep to follow up on a channel the caller prefers (email, SMS, callback).

    Configure the handoff phone number per agent at [**Channels → Phone**](https://platform.open.cx/channels/phone) → select the agent → **Agent Configuration**.
  </Accordion>

  <Accordion title="Caller identity" icon="id-card">
    When the caller is already a known OpenCX contact (matched by phone number), OpenCX merges with the existing Zendesk support user. Unknown callers get a Sunshine contact created with just the phone number until they identify further.
  </Accordion>

  <Accordion title="Recordings and OpenCX-side debug" icon="volume-high">
    Audio recordings and per-turn AI reasoning live on the OpenCX side. The **View session in OpenCX** link in the conversation summary opens the full playback, reasoning trace, and any tool calls the AI made during the call.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Phone Support" icon="phone" href="/phone/introduction">
    The channel itself — create the agent, configure, inbound and outbound.
  </Card>

  <Card title="Sunshine Conversations setup" icon="plug" href="/integrations/zendesk/sunshine-conversations">
    Credentials, webhook, and user merge.
  </Card>

  <Card title="Zendesk overview" icon="headset" href="/integrations/zendesk/overview">
    What else Zendesk lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/zendesk/troubleshooting">
    Transcript missing, handoff reason unclear.
  </Card>
</CardGroup>


# AI SMS Support
Source: https://docs.open.cx/integrations/zendesk/channels/sms

Route inbound SMS conversations from OpenCX into the Zendesk Agent Workspace as live Sunshine chats.

SMS conversations route through <Tooltip>Sunshine Conversations</Tooltip>. When the AI hands off an SMS thread, your rep picks it up as a live chat inside the Zendesk <Tooltip>Agent Workspace</Tooltip> and replies on the same number the customer texted.

## Pre-requisites

<Warning>
  **Connect and verify your SMS number first.** No inbound SMS can reach OpenCX until the channel is live — start with [Connect SMS](/sms/connect-sms) and come back here.
</Warning>

* **SMS number connected and verified** — see [Connect SMS](/sms/connect-sms) and, for US numbers, [SMS compliance](/sms/compliance).
* **Zendesk Sunshine credentials saved** — see [Sunshine Conversations](/integrations/zendesk/sunshine-conversations).

## How conversations land in Zendesk

```mermaid theme={"dark"}
flowchart LR
  A[Customer texts your SMS number] --> B[AI replies via SMS]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation closes]
  C -- No --> E[Handoff via Sunshine]
  E --> F[Live chat in Agent Workspace]
  F --> G[Rep replies — lands as SMS]
```

## Setting up

<Steps>
  <Step title="Confirm SMS is connected">
    Open [**Channels → SMS**](https://platform.open.cx/channels/sms) in the OpenCX dashboard. Your SMS number should be listed and active.
  </Step>

  <Step title="Confirm Sunshine is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **Zendesk → Messaging**. The status should show **Active**.
  </Step>

  <Step title="Trigger a test handoff">
    Text your connected number and ask to speak to a human. The AI should hand off.
  </Step>

  <Step title="Verify in the Zendesk Agent Workspace">
    The conversation should appear as a **live chat** tagged `opencx_channel_sms`. Reply from the Agent Workspace and confirm the response lands as an SMS on the customer's phone.
  </Step>
</Steps>

## What the rep sees

* A **live chat in the Agent Workspace** tagged `opencx_channel_sms`.
* Contact phone number attached via the Sunshine user.
* Full transcript of the AI-to-customer exchange.
* `opencx_session_id` on the conversation <Tooltip>`metadata`</Tooltip> — the trace key to the full OpenCX session.
* Replies deliver as SMS within a couple of seconds, carrier willing.

## Channel-specific details

<AccordionGroup>
  <Accordion title="US number compliance" icon="flag">
    US SMS numbers require <Tooltip>10DLC registration</Tooltip> or <Tooltip>toll-free verification</Tooltip> before they can reliably deliver outbound messages. Complete this on the OpenCX side — see [SMS compliance](/sms/compliance). The Zendesk integration doesn't change the requirement.
  </Accordion>

  <Accordion title="User merge by phone number" icon="phone">
    OpenCX matches Sunshine messaging contacts to existing Zendesk support users. SMS merges primarily on phone number; email is used only when the customer has shared one on another channel first.
  </Accordion>

  <Accordion title="Message length and segmentation" icon="ruler">
    SMS messages are split into 160-character segments by carriers. Reps in the Agent Workspace don't see the split — the full reply is sent as one logical message and the customer sees it as one thread. Keep replies tight; carrier costs scale per segment.
  </Accordion>

  <Accordion title="MMS" icon="image">
    Media sent by the customer (MMS) appears as attachments on the Sunshine conversation when the carrier supports it. Outbound MMS support depends on your SMS provider's capabilities.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI SMS Support" icon="comment-sms" href="/sms/introduction">
    The channel itself — connect, routing, compliance.
  </Card>

  <Card title="Sunshine Conversations setup" icon="plug" href="/integrations/zendesk/sunshine-conversations">
    Credentials, webhook, and user merge.
  </Card>

  <Card title="Zendesk overview" icon="headset" href="/integrations/zendesk/overview">
    What else Zendesk lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/zendesk/troubleshooting">
    Replies not reaching SMS, duplicate contacts.
  </Card>
</CardGroup>


# AI WhatsApp Support
Source: https://docs.open.cx/integrations/zendesk/channels/whatsapp

Route WhatsApp Business conversations from OpenCX into the Zendesk Agent Workspace as live Sunshine chats.

WhatsApp conversations route through <Tooltip>Sunshine Conversations</Tooltip>. When the AI hands off a WhatsApp thread, your rep picks it up as a live chat inside the Zendesk <Tooltip>Agent Workspace</Tooltip> and replies on the same number the customer wrote in on.

## Pre-requisites

<Warning>
  **Connect your WhatsApp Business number first.** No WhatsApp messages can reach OpenCX until the channel is live — start with [Connect WhatsApp](/whatsapp/connect-whatsapp) and come back here.
</Warning>

* **WhatsApp Business number connected** — see [Connect WhatsApp](/whatsapp/connect-whatsapp).
* **Zendesk Sunshine credentials saved** — see [Sunshine Conversations](/integrations/zendesk/sunshine-conversations).

## How conversations land in Zendesk

```mermaid theme={"dark"}
flowchart LR
  A[Customer messages your WhatsApp number] --> B[AI replies on WhatsApp]
  B --> C{AI can resolve?}
  C -- Yes --> D[Conversation closes]
  C -- No --> E[Handoff via Sunshine]
  E --> F[Live chat in Agent Workspace]
  F --> G[Rep replies — lands on WhatsApp]
```

## Setting up

<Steps>
  <Step title="Confirm WhatsApp is connected">
    Open [**Channels → WhatsApp**](https://platform.open.cx/channels/whatsapp) in the OpenCX dashboard. Your WhatsApp Business number should be listed and active.
  </Step>

  <Step title="Confirm Sunshine is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **Zendesk → Messaging**. The status should show **Active**.
  </Step>

  <Step title="Trigger a test handoff">
    Send a WhatsApp message to your connected number and ask to speak to a human. The AI should hand off.
  </Step>

  <Step title="Verify in the Zendesk Agent Workspace">
    The conversation should appear as a **live chat** tagged `opencx_channel_whatsapp`. Reply from the Agent Workspace and confirm the response lands on the customer's WhatsApp.
  </Step>
</Steps>

## What the rep sees

* A **live chat in the Agent Workspace** tagged `opencx_channel_whatsapp`.
* The contact's WhatsApp profile (name, phone number) attached via the Sunshine user.
* Full transcript of the AI-to-customer exchange so far.
* `opencx_session_id` on the conversation <Tooltip>`metadata`</Tooltip> — the trace key to the full OpenCX session.
* Replies land on the customer's WhatsApp within a couple of seconds.

## Channel-specific details

<AccordionGroup>
  <Accordion title="24-hour messaging window" icon="clock">
    WhatsApp's policy lets reps send free-form messages within 24 hours of the customer's last message. Outside that window, replies must use an approved <Tooltip>message template</Tooltip>. The Agent Workspace surfaces this constraint — reps will see template picker UI instead of the plain reply box.
  </Accordion>

  <Accordion title="User merge by phone number" icon="phone">
    OpenCX matches Sunshine messaging contacts to existing Zendesk support users when possible. WhatsApp contacts merge primarily on the phone number, and on email if the customer has shared one. No duplicate contact records.
  </Accordion>

  <Accordion title="Media messages" icon="image">
    Images, audio, and documents the customer sends on WhatsApp appear as attachments on the Sunshine conversation in the Agent Workspace. Size limits follow WhatsApp's per-media-type limits.
  </Accordion>

  <Accordion title="Proactive outbound" icon="paper-plane">
    Sending a WhatsApp template-message campaign from OpenCX is independent of the Zendesk integration — see the [WhatsApp channel docs](/whatsapp/introduction). Replies to a template land as a Sunshine conversation in the Agent Workspace once the customer engages.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI WhatsApp Support" icon="whatsapp" href="/whatsapp/introduction">
    The channel itself — connect, messaging rules, templates.
  </Card>

  <Card title="Sunshine Conversations setup" icon="plug" href="/integrations/zendesk/sunshine-conversations">
    Credentials, webhook, and user merge.
  </Card>

  <Card title="Zendesk overview" icon="headset" href="/integrations/zendesk/overview">
    What else Zendesk lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/zendesk/troubleshooting">
    Duplicate contacts, replies not reaching WhatsApp.
  </Card>
</CardGroup>


# AI Chat Widget
Source: https://docs.open.cx/integrations/zendesk/channels/widget

Route web chat conversations from the AI Chat Widget into the Zendesk Agent Workspace as live Sunshine chats.

Widget conversations route through <Tooltip>Sunshine Conversations</Tooltip>. When the AI hands off a chat, your rep picks it up as a live chat inside the Zendesk <Tooltip>Agent Workspace</Tooltip> — no ticket created, no context lost.

## Pre-requisites

<Warning>
  **Install the AI Chat Widget on your site first.** Zendesk handoff has nothing to route until the widget is live — start with [Install Widget](/widget/install-widget) and come back here.
</Warning>

* **Widget installed and reachable** — see [Install Widget](/widget/install-widget).
* **Zendesk Sunshine credentials saved** — see [Sunshine Conversations](/integrations/zendesk/sunshine-conversations).

## How conversations land in Zendesk

```mermaid theme={"dark"}
flowchart LR
  A[Visitor opens widget] --> B[AI answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Visitor closes the chat]
  C -- No --> E[Handoff via Sunshine]
  E --> F[Live chat in Agent Workspace]
  F --> G[Rep replies — lands in the widget]
```

## Setting up

<Steps>
  <Step title="Confirm the widget is live">
    Open the page where you embedded the widget and send a test message. You should see the AI respond. If the widget doesn't load, walk through [Install Widget](/widget/install-widget) first.
  </Step>

  <Step title="Confirm Sunshine is connected">
    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), open **Zendesk → Messaging**. The status should show **Active**. If not, complete the [Sunshine Conversations setup](/integrations/zendesk/sunshine-conversations).
  </Step>

  <Step title="Trigger a test handoff">
    Send a message like *"I want to talk to a human"* in the widget. The AI should hand off the conversation.
  </Step>

  <Step title="Verify in the Zendesk Agent Workspace">
    Open your Zendesk Agent Workspace. The conversation should appear as a **live chat** — not a ticket. Reply from Zendesk and confirm the message lands in the visitor's widget within a couple of seconds.
  </Step>
</Steps>

<Tip>
  If the conversation created a **ticket** instead of a live chat, Sunshine credentials are likely missing or inactive. Re-check [Settings → Integrations](https://platform.open.cx/settings/integrations) → Zendesk Messaging status.
</Tip>

## What the rep sees

* A **live chat in the Agent Workspace** on the same screen they work tickets from.
* The full AI-to-visitor transcript attached to the conversation.
* `opencx_channel_web` in Zendesk's view filters and reports.
* `opencx_org_id`, `opencx_contact_id`, and `opencx_session_id` on the conversation's <Tooltip>`metadata`</Tooltip> — the session ID is the trace key back to OpenCX.
* Replies typed in the Agent Workspace land back in the visitor's widget within a couple of seconds.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Authenticated visitors vs anonymous visitors" icon="shield-check">
    When the widget passes a verified email via [widget authentication](/widget/authentication), OpenCX merges the Sunshine messaging contact with the existing Zendesk support user on that email — no duplicate contact records. Anonymous visitors get a fresh Sunshine contact until they identify themselves.
  </Accordion>

  <Accordion title="Files visitors upload" icon="paperclip">
    Files uploaded in the widget appear as attachments on the Sunshine conversation in the Agent Workspace. File-size limits follow your Zendesk plan.
  </Accordion>

  <Accordion title="Widget custom components still render on the visitor side" icon="bolt">
    When an AI action returns data rendered by a [custom component](/widget/custom-components), the visitor sees the richer UI. Your rep sees the underlying text and data in the Agent Workspace — pick copy that reads well in both surfaces.
  </Accordion>

  <Accordion title="CSAT after the chat ends" icon="star">
    If your workflow triggers <Tooltip>CSAT</Tooltip>, the rating and comment land on the OpenCX session (visible via the **View session in OpenCX** link), not as a Zendesk satisfaction rating.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Chat Widget" icon="messages" href="/widget/introduction">
    The channel itself — install, configure, authenticate.
  </Card>

  <Card title="Sunshine Conversations setup" icon="plug" href="/integrations/zendesk/sunshine-conversations">
    Credentials, webhook, and user merge.
  </Card>

  <Card title="Zendesk overview" icon="headset" href="/integrations/zendesk/overview">
    What else Zendesk lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/zendesk/troubleshooting">
    Widget handoff creating a ticket instead, missing rep replies.
  </Card>
</CardGroup>


# Local test playbook
Source: https://docs.open.cx/integrations/zendesk/local_test_playbook



# Zendesk OAuth local test playbook

This playbook reproduces the local Zendesk OAuth validation used for the OpenCX Zendesk integration. It covers a fresh install, an existing legacy customer switching to OAuth, OAuth-only operation, same-account fallback, cross-account isolation, inbound messaging, replies, media, handoff, Agent Workspace, closing and reopening, uninstall, and reinstall.

Use a Zendesk development account and a disposable OpenCX organization. Do not run destructive lifecycle steps against a customer account.

## What must pass

| Product | Authorization | Required behavior |
| - | - | - |
| Ticketing | Legacy | Existing email, API token, webhook, ticket, and public-reply flows remain unchanged. |
| Ticketing | OAuth | Fresh connection creates usable ticketing settings, derives the default agent from the authorizing Zendesk user, and performs ticket/user/group/Guide/webhook operations without an API token. |
| Ticketing | Hybrid | OAuth is preferred. A revoked OAuth grant is fenced and the failing operation retries once with complete same-account legacy credentials. |
| Ticketing | Account mismatch | Legacy credentials from a different subdomain are never used as fallback. |
| Messaging | Legacy | Existing Sunshine App key, webhook, switchboard, inbound message, and handoff flows remain unchanged. |
| Messaging | OAuth | A fresh Marketplace install provisions an encrypted token and signed webhook, then supports inbound messages, deduplication, media, replies, handoff, close, and reopen. |
| Messaging | Hybrid | OAuth is preferred. Revoked OAuth retries the same operation once with complete same-account App credentials and marks OAuth for reconnect. |
| Messaging | Account mismatch | One Marketplace app is owned by one OpenCX organization; another org or subdomain fails closed. |
| Lifecycle | Both | State is bound to org, user, and browser session; replay is rejected; disconnect cancels outstanding callbacks; legacy credentials survive OAuth disconnect. |
| Uninstall | Messaging | A genuine Zendesk uninstall removes the OAuth installation locally, preserves legacy credentials, and permits a clean reinstall. |

## Prerequisites

* Node.js 24.
* Docker and the services in `backend/docker-compose.yml`.
* `cloudflared` for a public webhook origin.
* Google Chrome for the local full-stack browser test.
* A Zendesk development account with Support, Messaging, Agent Workspace, a Web Widget channel, and admin access.
* An approved OpenCX Marketplace bot for Messaging OAuth.
* An approved Zendesk global OAuth client for Ticketing OAuth. URL-construction tests can run with a test client ID, but successful consent requires the real approved client.
* An OpenCX development user with owner/admin access to a disposable organization.

## Keep credentials out of files

Never paste OAuth secrets, access tokens, callback codes, signed webhook URLs, widget keys, or Zendesk passwords into this document, a shell history entry, a test file, a commit, or CI output.

Store local secrets in macOS Keychain and expose them only to the process that needs them. For example:

```bash theme={"dark"}
security add-generic-password -U \
  -s opencx-zendesk-ticketing-oauth-secret \
  -a "$USER" \
  -w

security add-generic-password -U \
  -s opencx-zendesk-sunshine-oauth-secret \
  -a "$USER" \
  -w
```

Load values without printing them:

```bash theme={"dark"}
export ZENDESK_TICKETING_OAUTH_CLIENT_SECRET="$(security find-generic-password -w -s opencx-zendesk-ticketing-oauth-secret -a "$USER")"
export ZENDESK_SUNSHINE_OAUTH_CLIENT_SECRET="$(security find-generic-password -w -s opencx-zendesk-sunshine-oauth-secret -a "$USER")"
```

The backend uses these variables:

```bash theme={"dark"}
export ZENDESK_TICKETING_OAUTH_CLIENT_ID='<approved-global-client-id>'
export ZENDESK_TICKETING_OAUTH_CLIENT_SECRET='<from-keychain>'
export ZENDESK_SUNSHINE_OAUTH_CLIENT_ID='<approved-marketplace-client-id>'
export ZENDESK_SUNSHINE_OAUTH_CLIENT_SECRET='<from-keychain>'
export ZENDESK_MARKETPLACE_NAME='<marketplace-name>'
export ZENDESK_MARKETPLACE_ORGANIZATION_ID='<marketplace-organization-id>'
export ZENDESK_MARKETPLACE_BOT_ID='<marketplace-bot-id>'
export ZENDESK_OAUTH_REDIRECT_DASHBOARD_BASE_URL='http://localhost:3000'
```

Use literal values in `backend/.env` only when that ignored file is already the team's approved local secret store. Never add it to Git.

## Prepare the worktree

Run every command from the OAuth PR worktree, not a different checkout:

```bash theme={"dark"}
cd /path/to/opencx-oauth-worktree
git branch --show-current
git status --short
node --version
```

The branch must be the Zendesk OAuth PR branch and Node must report `v24.x`.

Install dependencies separately because backend and dashboard pin different pnpm versions:

```bash theme={"dark"}
cd backend
corepack pnpm install --frozen-lockfile

cd ../dashboard
corepack pnpm install --frozen-lockfile
```

If a private `@opencx-labs/*` package returns `401` or `403`, repair the Keychain-backed GitHub Packages token first. Do not share another worktree's `node_modules`; cross-worktree symlinks caused the incorrect local font and incomplete dependency tree seen during the original validation.

## Start local infrastructure

```bash theme={"dark"}
cd backend
docker compose up -d
pnpm dev:prepare
```

The required local ports are:

| Service | Port |
| - | - |
| Dashboard | `3000` |
| Backend | `8080` |
| Zendesk webhook proxy | `18080` |
| Static widget page | `18081` |
| PostgreSQL | `5432` |
| Redis | `6379` |

## Create a narrow public webhook proxy

Do not tunnel the entire local backend. The proxy below exposes only the signed Zendesk webhook route and Marketplace uninstall route, while capturing the latest event for the live test.

Create `/tmp/opencx-zendesk-webhook-proxy.mjs`:

```js theme={"dark"}
import http from "node:http";
import { writeFileSync } from "node:fs";

const webhookPrefix = "/backend/zendesk/webhook/";
const uninstallPath = "/backend/zendesk-sunshine-oauth/uninstall";

http
  .createServer(async (request, response) => {
    if (request.method === "HEAD") {
      response.writeHead(200);
      response.end();
      return;
    }

    const allowed =
      request.method === "POST" &&
      (request.url?.startsWith(webhookPrefix) || request.url === uninstallPath);
    if (!allowed) {
      response.writeHead(404);
      response.end();
      return;
    }

    const chunks = [];
    for await (const chunk of request) chunks.push(chunk);
    const body = Buffer.concat(chunks);
    if (request.url?.startsWith(webhookPrefix)) {
      writeFileSync("/tmp/opencx-last-zendesk-webhook.json", body, { mode: 0o600 });
    }

    const upstream = http.request(
      {
        host: "127.0.0.1",
        port: 8080,
        method: request.method,
        path: request.url,
        headers: request.headers,
      },
      (upstreamResponse) => {
        response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
        upstreamResponse.pipe(response);
      },
    );
    upstream.on("error", () => {
      if (!response.headersSent) response.writeHead(502);
      response.end();
    });
    upstream.end(body);
  })
  .listen(18080, "127.0.0.1");
```

Start it and the tunnel:

```bash theme={"dark"}
node /tmp/opencx-zendesk-webhook-proxy.mjs
cloudflared tunnel --url http://127.0.0.1:18080
```

Copy only the generated HTTPS origin, without a trailing slash:

```bash theme={"dark"}
export SERVER_BASE_URL='https://<generated-host>.trycloudflare.com'
```

Start the backend after `SERVER_BASE_URL` is set. The OAuth callback uses it to provision the real Zendesk webhook target.

```bash theme={"dark"}
cd backend
pnpm ddev
```

Confirm the public proxy is narrow:

```bash theme={"dark"}
curl -I "$SERVER_BASE_URL/"
```

A `HEAD` request returns success for tunnel health. An unrelated `GET` or `POST` path must return `404`.

## Start the dashboard

Set the local backend URL in `dashboard/.env`:

```bash theme={"dark"}
VITE_BACKEND_URL=http://localhost:8080
```

Then start the dashboard:

```bash theme={"dark"}
cd dashboard
pnpm xdev
```

Open `http://localhost:3000/auth`, use **Dev login**, select the disposable org, then open **Settings → Integrations → Zendesk**.

The first page must show exactly two product choices: **Zendesk Ticketing** and **Zendesk Messaging**. Selecting a product must show exactly two authorization choices: **OAuth** and **Legacy credentials**. OAuth carries the **New** and **Recommended** badges.

## Run the full-stack modal test

This test uses the real local backend and system Chrome without downloading a Playwright browser revision:

```bash theme={"dark"}
cd dashboard
PLAYWRIGHT_USE_SYSTEM_CHROME=1 \
E2E_WITH_BACKEND=1 \
E2E_ZENDESK_OAUTH_START=1 \
VITE_BACKEND_URL=http://localhost:8080 \
node_modules/.bin/playwright test \
  e2e/zendesk-oauth-setup.e2e.ts \
  --project=chromium \
  --reporter=list
```

It verifies the two-stage selector, both Legacy forms, both OAuth panels, invalid Ticketing subdomains, real start URL construction, callback-error routing, status isolation, the Ticketing reply webhook, and trigger-instructions link.

## Ticketing OAuth: Zendesk-side setup

1. In OpenCX choose **Zendesk → Ticketing → OAuth**.
2. Enter only the Zendesk subdomain, such as `acme`.
3. Click **Continue to Zendesk**.
4. Confirm the Zendesk hostname matches the entered subdomain.
5. Sign in as an agent or admin and click **Allow**.
6. Confirm OpenCX returns to the OAuth panel with **Connected** and the correct subdomain.
7. Copy the signed **Reply webhook URL** shown in the panel.
8. In Zendesk Admin Center open **Apps and integrations → Webhooks** and create a `POST` JSON webhook with no extra authentication.
9. Open **Objects and rules → Triggers** and create the following trigger:
   * Meet ANY: Ticket is Created; Ticket is Updated.
   * Meet ALL: Comment is Present (public).
   * Action: notify the OpenCX active webhook.
   * Body:

```json theme={"dark"}
{
  "ticketId": "{{ticket.id}}",
  "event_type": "new_comment"
}
```

OAuth authenticates OpenCX's outbound Support API calls. The classic trigger is independently required for inbound public-comment delivery. Never put comment text in the webhook body; OpenCX fetches and filters public comments itself.

If the global client has not yet been approved, stop after the automated start-URL test. A test client ID can prove URL construction but cannot prove consent, token exchange, or refresh rotation.

## Messaging OAuth: Zendesk-side setup

1. In OpenCX choose **Zendesk → Messaging → OAuth** and click **Continue to Zendesk**.
2. Zendesk opens the OpenCX Marketplace bot authorization. Click **Allow** once.
3. For a local backend, Zendesk may redirect to the registered production callback origin. Before that callback is consumed, replace only the origin with `http://localhost:8080`, preserving `/backend/zendesk-sunshine-oauth/callback` and the entire query string byte-for-byte. Do not reload or reuse a callback code.
4. Confirm the local callback returns to `http://localhost:3000/settings/integrations` and shows **Connected**.
5. In Zendesk Admin Center open **AI → AI agents → AI agents → Marketplace bots → OpenCX**.
6. Assign OpenCX to one disposable Web Widget or staging channel and save.
7. In **Channels → Messaging and social → Messaging**, make OpenCX the test channel's default responder.
8. Set **Conversation control** to **Release control** so a closed Agent Workspace conversation returns to OpenCX on the next customer message.

The OAuth callback automatically provisions the integration-scoped webhook. Do not manually create a second Sunshine webhook for the OAuth path.

## Create the local Web Widget page

Get the test channel's Web Widget key from Zendesk Admin Center, then create `/tmp/opencx-zendesk-widget.html` without committing it:

```html theme={"dark"}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>OpenCX Zendesk OAuth live test</title>
  </head>
  <body>
    <h1>OpenCX Zendesk OAuth live test</h1>
    <script
      id="ze-snippet"
      src="https://static.zdassets.com/ekr/snippet.js?key=<WEB_WIDGET_KEY>"
    ></script>
  </body>
</html>
```

Serve and open it:

```bash theme={"dark"}
python3 -m http.server 18081 --directory /tmp
open http://localhost:18081/opencx-zendesk-widget.html
```

Send a unique message such as `OAuth live inbound <UUID>`. Wait for `/tmp/opencx-last-zendesk-webhook.json`, then extract the live values without printing the whole webhook:

```bash theme={"dark"}
export ZENDESK_SUNSHINE_LIVE_CONVERSATION_ID="$(jq -r '.events[0].payload.conversation.id' /tmp/opencx-last-zendesk-webhook.json)"
export ZENDESK_SUNSHINE_LIVE_INBOUND_TEXT="$(jq -r '.events[0].payload.message.content.text' /tmp/opencx-last-zendesk-webhook.json)"
export ZENDESK_SUNSHINE_LIVE_ORG_ID='<disposable-opencx-org-id>'
```

## Run the real Messaging OAuth lifecycle

`CI_SKIP_FLAKY_TESTS` must be absent. Setting it to `false` still skips tests because any nonempty value is truthy in the test environment.

```bash theme={"dark"}
cd backend
env -u CI_SKIP_FLAKY_TESTS \
  ZENDESK_SUNSHINE_LIVE_ORG_ID="$ZENDESK_SUNSHINE_LIVE_ORG_ID" \
  ZENDESK_SUNSHINE_LIVE_CONVERSATION_ID="$ZENDESK_SUNSHINE_LIVE_CONVERSATION_ID" \
  ZENDESK_SUNSHINE_LIVE_INBOUND_TEXT="$ZENDESK_SUNSHINE_LIVE_INBOUND_TEXT" \
  pnpm test \
    src/zendesk-integration/sunshine/__tests__/sunshine-oauth-marketplace-live-lifecycle.e2e.spec.ts \
    --reporter=verbose
```

The test proves:

* the active auth is a Marketplace bearer;
* the database value is encrypted at rest;
* Zendesk has the expected signed webhook target;
* the real inbound webhook created a contact, session, conversation mapping, and history row;
* replaying the captured webhook does not duplicate the inbound message;
* an OpenCX business reply and image reach the real Zendesk conversation;
* handoff transfers switchboard control to `zd:agentWorkspace`;
* a post-handoff OpenCX agent reply reaches Zendesk and remains one local agent message.

## Manual Agent Workspace and reopen checks

After the live spec:

1. Open the real conversation in Zendesk Agent Workspace.
2. Send a unique public agent reply.
3. Confirm the customer sees it in the Web Widget and OpenCX stores it once as an agent message.
4. Solve and close the Agent Workspace conversation.
5. Confirm the OpenCX session closes and the Zendesk ticket reaches the expected terminal state.
6. Send another unique customer message from the widget.
7. Confirm routing returns to OpenCX, a new OpenCX session is created, and the new lifecycle does not append to the sealed session.

## Legacy, hybrid, and isolation regressions

Run the focused real Zendesk matrix with flaky skipping unset:

```bash theme={"dark"}
cd backend
env -u CI_SKIP_FLAKY_TESTS VITEST_MAX_WORKERS=1 pnpm test \
  src/zendesk-integration-v2/__tests__/oauth-e2e/real-oauth-ticket-lifecycle.e2e.spec.ts \
  src/zendesk-integration-v2/__tests__/oauth-e2e/real-basic-auth-org-unaffected-by-oauth-support.e2e.spec.ts \
  src/zendesk-integration-v2/__tests__/oauth-e2e/real-oauth-revoked-api-request-context-falls-back-to-basic.e2e.spec.ts \
  src/zendesk-integration-v2/__tests__/oauth-e2e/real-oauth-revoked-api-request-context-fails-closed.e2e.spec.ts \
  src/zendesk-integration-v2/__tests__/oauth-e2e/real-oauth-revoked-webhook-provisioning-falls-back-to-basic.e2e.spec.ts \
  src/zendesk-integration/sunshine/__tests__/get-zendesk-ticketing-creds-cross-store-revoked-oauth-falls-back-to-basic.e2e.spec.ts \
  src/livekit-voice-agent/__tests__/contact-enrichment.revoked-oauth.real-zendesk.spec.ts \
  --reporter=verbose
```

Then run the local DB/HTTP defensive matrix:

```bash theme={"dark"}
pnpm test \
  src/zendesk-integration-v2/__tests__/zendesk-ticketing-oauth-callback-rejects-different-user.spec.ts \
  src/zendesk-integration-v2/__tests__/zendesk-ticketing-oauth-callback-rejects-different-user-org.spec.ts \
  src/zendesk-integration-v2/__tests__/zendesk-ticketing-oauth-callback-rejects-different-session.spec.ts \
  src/zendesk-integration-v2/__tests__/zendesk-ticketing-oauth-disconnect-cancels-callback.spec.ts \
  src/zendesk-integration/sunshine/__tests__/sunshine-oauth-concurrent-app-claim-has-one-owner.spec.ts \
  src/zendesk-integration/sunshine/__tests__/sunshine-oauth-lifecycle-generation.spec.ts \
  src/zendesk-integration/sunshine/__tests__/sunshine-oauth-stale-401-does-not-poison-current-token.spec.ts \
  src/zendesk-integration/sunshine/__tests__/sunshine-oauth-expired-hybrid-falls-back-to-legacy.spec.ts \
  --reporter=verbose
```

## Uninstall and reinstall

Zendesk's Marketplace uninstall callback is unauthenticated. OpenCX accepts cleanup only after the stored bearer proves revoked. Therefore:

1. Remove the OpenCX Marketplace bot through Zendesk first.
2. Wait for Zendesk's Remove URL callback.
3. If the saved Remove URL points to production and cannot reach the local backend, replay the same uninstall notification to the local public tunnel only after the real Zendesk removal has revoked the bearer:

```bash theme={"dark"}
curl -X POST "$SERVER_BASE_URL/backend/zendesk-sunshine-oauth/uninstall" \
  -H 'content-type: application/json' \
  --data '{"appId":"<installed-app-id>","integrationId":"<zendesk-integration-id>"}'
```

4. Confirm Messaging OAuth status is disconnected.
5. Confirm any Legacy Sunshine credentials still exist and remain usable.
6. Confirm an OAuth-only org no longer routes through Zendesk when neither Ticketing nor Legacy Sunshine auth remains.
7. Start Messaging OAuth again, click **Allow**, reassign the bot to the staging channel, and confirm a new inbound message works.

Never send the uninstall callback while the bearer is active. OpenCX must retain the connection because an active bearer means the callback is forged or stale.

## Final verification before pushing

```bash theme={"dark"}
cd backend
pnpm tsgo
pnpm voice:test

cd ../dashboard
pnpm type-check

cd ..
git diff --check
```

Also run scoped formatter and linter checks for every changed backend, dashboard, test, and docs file. Review the entire diff, then run an independent PR review before committing.

The completion record should include:

* exact test commands and pass counts;
* proof that `CI_SKIP_FLAKY_TESTS` was unset for live tests;
* the test Zendesk subdomain and disposable OpenCX org, but no secrets;
* confirmation that the installed token was encrypted at rest;
* confirmation that webhook replay deduplicated;
* confirmation that Agent Workspace reply, close, reopen, uninstall, and reinstall worked;
* CI and reviewer status on the pushed PR.

## Troubleshooting

### `Partner in query parameter 'client_id' not found`

The Marketplace client ID is not approved, not published to the selected Zendesk environment, or does not match `ZENDESK_SUNSHINE_OAUTH_CLIENT_ID`. This is a Zendesk Marketplace registration problem, not a customer API-token problem.

### Ticketing authorize URL opens but consent fails

Confirm the global OAuth client is approved for the exact client ID and callback URL. A tenant-local OAuth client cannot behave as the global client used by this integration.

### Callback lands on `api.open.cx` during local testing

Before consuming the one-time callback, replace only the origin with `http://localhost:8080`. Preserve the path, code, state, and encoding. Never paste the callback URL into logs or a ticket.

### Callback says state is invalid or expired

Start a new OAuth flow in the same authenticated browser session. State is intentionally one-time, short-lived, and bound to the exact OpenCX user, org, and session.

### No Messaging webhook arrives

Check all of the following:

* backend started after `SERVER_BASE_URL` was set to the current tunnel;
* the Marketplace bot is assigned to the test channel;
* the channel's default responder is OpenCX;
* the OAuth status is connected and does not require reconnect;
* the public proxy receives only the expected signed webhook path;
* Conversation control is set to Release control for return routing.

### Ticketing agent replies do not return to OpenCX

OAuth does not replace the Zendesk trigger. Confirm the signed Reply webhook URL, `POST` JSON webhook, Created-or-Updated public-comment trigger, and exact `ticketId`/`event_type` body.

### Dashboard font or components look different from production

Verify the dashboard uses branch-local dependencies. Remove a broken `node_modules` symlink and reinstall with the correct dashboard pnpm version and a working private-package token. The expected UI font is Inter.

### A real test is reported as skipped

Run it with `env -u CI_SKIP_FLAKY_TESTS`. Do not set the variable to `false`.

### AI reply assertions fail with an OpenRouter authentication error

Repair the local OpenRouter test credential. That error is independent of Zendesk OAuth and should not be hidden by changing OAuth expectations.

## Cleanup

1. Delete every temporary Zendesk ticket, user, webhook, trigger, and channel assignment created by the run.
2. Leave the Marketplace bot installed only if the disposable org is intended to remain connected; otherwise uninstall it through Zendesk and verify local cleanup.
3. Stop dashboard, backend, widget server, webhook proxy, and `cloudflared`.
4. Remove only these explicit temporary files:

```bash theme={"dark"}
rm /tmp/opencx-zendesk-webhook-proxy.mjs
rm /tmp/opencx-zendesk-widget.html
rm /tmp/opencx-last-zendesk-webhook.json
```

5. Stop Docker services when they are no longer needed:

```bash theme={"dark"}
cd backend
docker compose down
```

Do not delete shared development databases, volumes, credentials, or another worktree's dependencies as part of cleanup.


# Zendesk overview
Source: https://docs.open.cx/integrations/zendesk/overview

Run Zendesk as the surface your agents work in while OpenCX resolves, routes, and grounds every conversation in your Help Center.

OpenCX works alongside your agents inside Zendesk. The AI resolves what it can, escalates what it can't, grounds every answer in your <Tooltip>Help Center</Tooltip>, and files every handoff straight into the ticket or <Tooltip>Sunshine Conversations</Tooltip> thread your reps already live in — no separate inbox, no context rebuild.

<Tip>
  Setup starts at [**Settings → Integrations**](https://platform.open.cx/settings/integrations) in your OpenCX dashboard. Select **Zendesk**, choose **Ticketing** or **Messaging**, then choose **OAuth** (recommended) or **Legacy credentials**.
</Tip>

## What you get

<AccordionGroup>
  <Accordion title="Tickets your reps pick up with full context" icon="ticket">
    When the AI escalates, OpenCX opens (or appends to) a Zendesk <Tooltip>ticket</Tooltip> using your existing triggers, groups, and SLAs. The conversation summary becomes the description, the full transcript lands as the first comment, the source channel is tagged, and any <Tooltip>custom fields</Tooltip> you map are filled before an agent opens the ticket.
  </Accordion>

  <Accordion title="One thread from the first message to resolution" icon="reply">
    Public replies your reps send from Zendesk travel back to the contact on the channel they wrote in — email, SMS, WhatsApp, web widget. Internal notes stay private. No copy-pasting, no "reopen the other tool" detours.
  </Accordion>

  <Accordion title="Every answer traced to your own content" icon="book">
    OpenCX syncs your Help Center on a schedule. Edits, new articles, and <Tooltip>internal-only content</Tooltip> propagate without re-training. The AI shows its source so your reps can audit a draft in one click.
  </Accordion>

  <Accordion title="Custom fields the AI fills, so your views keep working" icon="list-check">
    Map any Zendesk custom field to a short description of what it represents. On handoff, OpenCX picks the value — dropdowns stay inside your existing options; text fields get structured strings. Your saved views, triggers, and reports work on day one.
  </Accordion>
</AccordionGroup>

## Supported channels

Pick the channel you want to wire through Zendesk — each page covers the implementation details for that channel on top of the shared Zendesk setup.

<CardGroup>
  <Card title="AI Chat Widget" icon="comments" href="/integrations/zendesk/channels/widget">
    Live chat handoff into the Zendesk Agent Workspace via Sunshine.
  </Card>

  <Card title="AI WhatsApp Support" icon="whatsapp" href="/integrations/zendesk/channels/whatsapp">
    Business WhatsApp threads routed to the Agent Workspace.
  </Card>

  <Card title="AI SMS Support" icon="comment-sms" href="/integrations/zendesk/channels/sms">
    Inbound SMS handed off as live Sunshine conversations.
  </Card>

  <Card title="AI Phone Support" icon="phone" href="/integrations/zendesk/channels/phone">
    Voice conversations with transcript attached for your reps.
  </Card>

  <Card title="AI Email Support" icon="envelope" href="/integrations/zendesk/channels/email">
    Email handoff creates a Zendesk ticket with the thread attached.
  </Card>
</CardGroup>

## Observability

Every conversation OpenCX hands to Zendesk is traceable from the Zendesk side back to the exact OpenCX session. Your reps debug in the tool they're already in; your admins audit without re-running the AI.

<AccordionGroup>
  <Accordion title="Session ID on every ticket" icon="fingerprint">
    OpenCX writes the session UUID into Zendesk's <Tooltip>`external_id`</Tooltip>. Searching or filtering tickets by `external_id` surfaces the exact OpenCX thread — useful when a rep needs to know "which conversation produced this ticket?"
  </Accordion>

  <Accordion title="Back-link to OpenCX inside the first comment" icon="link">
    The first comment on every OpenCX-created ticket includes a **View session in OpenCX** link. One click opens the full transcript, tool calls, AI reasoning, and handoff reason in your OpenCX Inbox — no ticket-ID lookup required.
  </Accordion>

  <Accordion title="Tags you can filter views and reports by" icon="tag">
    OpenCX applies a consistent tag set on every ticket: `opencx` always, plus tags for mode (`opencx_autopilot`, `opencx_handedoff`), source channel (`opencx_channel_<name>`), detected sentiment (`opencx_sentiment_<value>`), and conversation language (`opencx_language_<code>`). Build Zendesk views and reports on these without touching OpenCX.
  </Accordion>

  <Accordion title="Sunshine conversation metadata" icon="messages">
    For channels routed through Sunshine Conversations, OpenCX attaches `opencx_org_id`, `opencx_contact_id`, and `opencx_session_id` to every conversation's `metadata`. Your reps don't see these directly, but they're reachable via the Conversations API for debugging and analytics.
  </Accordion>
</AccordionGroup>

<Note>
  Want a specific tag or field you don't see here? Mention it during onboarding — tag application is configurable per organization.
</Note>

## Pick your setup path

Most teams run both — Ticketing for email, Sunshine for everything real-time. Start with one and add the other later.

<Tabs>
  <Tab title="Sunshine Conversations">
    Use <Tooltip>Sunshine Conversations</Tooltip> for every real-time channel — web widget, SMS, WhatsApp, Messenger, Instagram, and phone handoffs. Conversations land in the Zendesk <Tooltip>Agent Workspace</Tooltip> as live chats, not tickets.

    Authorization: use **OAuth** to install the OpenCX Marketplace bot without copying API keys. Existing customers can keep using, or switch from, the legacy Sunshine <Tooltip>App key</Tooltip>, subdomain, and <Tooltip>App ID</Tooltip>.

    <Card title="Set up Sunshine Conversations" icon="messages" href="/integrations/zendesk/sunshine-conversations">
      Connect Sunshine for live chat, SMS, WhatsApp, and social.
    </Card>
  </Tab>

  <Tab title="Ticketing API — Email">
    Use the Ticketing API for <Tooltip>asynchronous channels</Tooltip> — primarily **email**. OpenCX creates a Zendesk ticket on handoff and syncs your reps' replies back to the contact's inbox.

    Authorization: use **OAuth** so OpenCX does not store an API token. Legacy customers can continue using their Zendesk subdomain, admin email, and <Tooltip>API token</Tooltip>. Both modes use the signed OpenCX reply webhook and Zendesk trigger.

    <Card title="Set up Ticketing API" icon="envelope" href="/integrations/zendesk/ticketing-api">
      Authorize with OAuth or keep Legacy credentials, then register the reply webhook.
    </Card>
  </Tab>
</Tabs>

***

## Related Documentation

<CardGroup>
  <Card title="Help Center Sync" icon="book" href="/knowledge/sources/zendesk/connect">
    Train the AI on your Help Center articles.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/zendesk/channels/widget">
    Per-channel implementation details on top of the shared setup.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/zendesk/troubleshooting">
    Tickets not creating, replies missing, sync stuck.
  </Card>
</CardGroup>


# Sunshine Conversations
Source: https://docs.open.cx/integrations/zendesk/sunshine-conversations

Route chat, SMS, WhatsApp, phone, and social handoffs from OpenCX straight into the Zendesk Agent Workspace.

Sunshine Conversations is Zendesk's real-time messaging layer. Use this path for every channel **except email** — the web chat widget, SMS, WhatsApp, Messenger, Instagram, and phone handoffs. Conversations land in the Zendesk <Tooltip>Agent Workspace</Tooltip> as live chats your reps pick up with full context attached.

<ZendeskSunshineFlow />

<Info>
  Sunshine Conversations is included with the **Zendesk Suite** plan. If you're
  on Support Professional, use the [Ticketing
  API](/integrations/zendesk/ticketing-api) path for email handoff and contact
  Zendesk to upgrade for real-time channels.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Zendesk Suite plan with Sunshine provisioned" icon="circle-check">
    Open [**Admin Center → Apps and integrations → APIs → Conversations API**](https://admin.zendesk.com/apps/integrations/apis/conversations-api). If the section is missing, Sunshine isn't provisioned on your account — contact Zendesk.
  </Accordion>

  <Accordion title="Admin access in Zendesk" icon="user-shield">
    You'll create an App key in the Conversations API section and note your

    <Tooltip>
      App ID
    </Tooltip>

    . Agent roles don't have access.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="key">
    Required to save integration settings in [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Accordion>
</AccordionGroup>

## Choose authorization

Open [**Settings → Integrations**](https://platform.open.cx/settings/integrations), select **Zendesk → Messaging**, then choose:

* **OAuth — recommended:** install and authorize the OpenCX Marketplace bot. OpenCX provisions the integration webhook automatically; no Sunshine App key is stored.
* **Legacy credentials:** enter the Sunshine App ID, App key, secret, and integration ID. Existing installations continue to work and can switch to OAuth without deleting their legacy credentials first.

## OAuth setup (recommended)

<Steps>
  <Step title="Choose Messaging OAuth">
    In OpenCX, open **Settings → Integrations → Zendesk → Messaging → OAuth**, then click **Continue to Zendesk**.
  </Step>

  <Step title="Install and authorize OpenCX">
    Sign in to the Zendesk account you want to connect, review the Marketplace bot authorization, and click **Allow**. OpenCX verifies the individual Zendesk bot installation, claims it for your OpenCX organization, creates the signed webhook, and returns you to a **Connected** status.

    <Warning>
      One Zendesk Marketplace bot installation can belong to only one OpenCX organization. OpenCX rejects a second organization instead of sending the same customer events to two tenants.
    </Warning>
  </Step>

  <Step title="Assign the bot to a test channel">
    In Zendesk Admin Center, open **AI → AI agents → AI agents → Marketplace bots → OpenCX**. Select one staging Web Widget, mobile, or social channel and save. Expand to production channels only after the test matrix passes.
  </Step>

  <Step title="Configure conversation handback">
    In **Channels → Messaging and social → Messaging**, set **Conversation control** to **Release control**. Make OpenCX the channel's default responder and confirm your Solved-to-Closed timing. These routing settings apply to both OAuth and Legacy authorization.
  </Step>

  <Step title="Verify end to end">
    Send a new message through the assigned channel, confirm an OpenCX session is created, hand off to Zendesk Agent Workspace, reply as an agent, then solve and close the conversation. A later customer message should return to OpenCX and create a new session.
  </Step>
</Steps>

## Legacy App key setup

<Steps>
  <Step title="Create a Sunshine App key">
    In Zendesk, open [**Admin Center → Apps and integrations → APIs → Conversations API**](https://admin.zendesk.com/apps/integrations/apis/conversations-api).

    1. Click **Create API key**.
    2. Label it `OpenCX`.
    3. **Copy the Key ID and Secret** — Zendesk only shows the Secret once.
    4. Note the **App ID** displayed at the top of the page.

    <Warning>
      **Generate an App key, not an Integration key.** The Key ID starts with `app_` for an App key. Integration keys are scoped to a single Sunshine integration and will fail authentication against OpenCX. If your Key ID doesn't start with `app_`, delete it and create a new key from the **Conversations API** section (not from inside a specific integration).
    </Warning>

    <Warning>
      Lose the Secret? Delete the key and generate a new one. Zendesk does not let you retrieve the Secret after the dialog closes.
    </Warning>
  </Step>

  <Step title="Turn on multi-conversations for the Sunshine app">
    OpenCX creates a fresh Sunshine conversation for every chat session. Sunshine's default `personal` conversation mode caps each end user at **one** open conversation, so the second `POST /v2/apps/{appId}/conversations` for the same user fails and the session never reaches the Agent Workspace. Turn multi-conversations on once, in Zendesk, before you wire up OpenCX.

    1. In Admin Center, go to **Channels → Messaging and social → Messaging**.
    2. Click **Manage settings** at the top of the page.
    3. Under **Web Widget and Mobile SDKs**, expand **Multi-conversations** and click **Set up multi-conversations**.
    4. Click **Turn on multi-conversations for your account** and select **every** Web Widget, iOS SDK, and Android SDK channel OpenCX will answer on.
    5. **Save settings.**

    See [Allowing multiple conversations for your end users](https://support.zendesk.com/hc/en-us/articles/8008427696410-Allowing-multiple-conversations-for-your-end-users) for the full Zendesk walkthrough.

    <Warning>
      **This change is irreversible.** Once enabled, end users keep access to their conversations list forever — there's no toggle back to the single-conversation experience. You can later remove the **New conversation** button from a channel, but the list itself stays. Read [Zendesk's considerations](https://support.zendesk.com/hc/en-us/articles/8008427696410-Allowing-multiple-conversations-for-your-end-users#topic_yhy_vjy_1dc) before flipping the switch.
    </Warning>

    <Info>
      **Pick every Web/iOS/Android channel.** Turning multi-conversations on for one channel updates the underlying Sunshine app for **all** Web/iOS/Android channels — channels you leave unselected just lose the **New conversation** button. Selecting all of them keeps the end-user experience consistent and avoids surprises when you add the next channel. Social channels (WhatsApp, Messenger, Instagram) don't support multi-conversations and aren't affected by this setting.
    </Info>

    <Tip>
      Prefer to flip it without leaving your terminal? Same effect via the Conversations API:

      ```bash theme={"dark"}
      curl -X PATCH "https://api.smooch.io/v2/apps/{APP_ID}" \
        -u "{KEY_ID}:{SECRET}" \
        -H "Content-Type: application/json" \
        -d '{"settings": {"multiConvoEnabled": true}}'
      ```

      Same irreversibility caveat applies. Confirm with `GET /v2/apps/{APP_ID}` — `settings.multiConvoEnabled` should come back `true`.
    </Tip>
  </Step>

  <Step title="Open Zendesk Messaging in OpenCX">
    In OpenCX, go to [**Settings →
    Integrations**](https://platform.open.cx/settings/integrations), find
    **Zendesk**, and click **Zendesk Messaging**.
  </Step>

  <Step title="Copy your messaging webhook URL">
    OpenCX shows a **Messaging Webhook URL** on the form right away — you don't
    need to save first. Copy it now; you'll register it in Zendesk in the next
    step, **before** you save your credentials.
  </Step>

  <Step title="Register the webhook in Sunshine">
    In Zendesk's **Conversations API** admin, open the **Integrations / Webhooks** panel for your app and add a new webhook.

    | Field | Value |
    | - | - |
    | **Target URL** | Paste the OpenCX messaging webhook URL. |
    | **Triggers** | Enable **all** triggers. OpenCX needs at minimum `conversation:message` (inbound messages), `conversation:create` (drives the connection self-test on save), and `switchboard:releaseControl` (returns the conversation to the AI after a human resolves it). Missing any of these breaks either setup or handback. |
    | **Secret** | Leave blank — OpenCX validates by signed URL. |

    Save the webhook.
  </Step>

  <Step title="Enter your Sunshine credentials">
    | Field | Value |
    | - | - |
    | **Subdomain** | The `acme` part of `acme.zendesk.com`. Same subdomain used for Ticketing. |
    | **App ID** | The Sunshine <Tooltip>App ID</Tooltip> from the Conversations API page. |
    | **Key ID** | The ID from the App key you just created — starts with `app_`. |
    | **Secret** | The secret you copied. |
    | **Integration ID** | The ID of the **OpenCX** Conversations integration in Zendesk (see warning below). Find it under [**Admin Center → Apps and integrations → Integrations → Conversations integrations**](https://admin.zendesk.com/apps/integrations/integrations/conversations-integrations). |

    <Warning>
      **The Conversations integration MUST be named exactly `opencx`** (lowercase). This name is how OpenCX's switchboard wiring identifies which integration owns each conversation, and it's also how the AI agent shows up in Zendesk's AI Agents Marketplace (next step). Any other spelling — `OpenCX`, `open-cx`, `opencx-prod`, etc. — and routing will silently break.

      If you've already created the integration with a different name, delete it from **Conversations integrations** and recreate it with the exact name `opencx`, then copy the new Integration ID here.
    </Warning>

    Click **Test and Save**.

    <Warning>
      **Register the webhook first (previous step).** Test and Save runs a live connection check — OpenCX opens a test conversation and waits for Zendesk to call your webhook back. If the webhook isn't registered yet, the check times out with *"Waited to receive a webhook callback from Zendesk, but didn't receive any."* and nothing saves.
    </Warning>
  </Step>

  <Step title="Provide a Zendesk API token for user merge">
    Sunshine uses a separate identity model from Zendesk's support API. To prevent the same person from showing up as two separate <Tooltip>Zendesk users</Tooltip>, OpenCX merges Sunshine messaging contacts with matching Zendesk support users.

    In the **Zendesk API credentials** panel on the same page, reuse the credentials from the [Ticketing API](/integrations/zendesk/ticketing-api) setup. The merge endpoint uses the same token. If you skipped Ticketing, generate a token for this purpose alone — user search is free on every Zendesk plan, and no webhook is needed.

    <Info>
      **What OpenCX writes on every Sunshine conversation** — `metadata.opencx_org_id`, `metadata.opencx_contact_id`, and `metadata.opencx_session_id`. Your reps don't see these fields directly, but they're reachable via the Conversations API for debugging and analytics. The session ID is the trace key back to the exact OpenCX conversation.
    </Info>
  </Step>

  <Step title="Pick the channels OpenCX should answer on">
    Saving credentials only wires up the integration — Zendesk still needs to be told which channels the OpenCX AI agent should actually respond on. This is done from Zendesk's AI Agents admin (not from OpenCX).

    1. In your Zendesk Admin Center, go to **AI → AI agents → AI agents**, then click the **Marketplace bots** tab. (Direct admin URLs are subdomain-scoped, so we can't link them — see Zendesk's [Managing third-party bots in Admin Center](https://support.zendesk.com/hc/en-us/articles/5064149334426-Managing-third-party-bots-in-Admin-Center) for the canonical walkthrough.)
    2. Find the **OpenCX** entry in the list of marketplace bots and open it.
    3. Under **Channels**, pick every channel you want the AI agent to handle — specific WhatsApp numbers, the Web Widget, Facebook Messenger pages, Instagram accounts, SMS numbers, etc. To make OpenCX the first responder for *every* messaging channel instead, use the entry's **Options → Assign default** menu — see [Setting an advanced AI agent as the default responder](https://support.zendesk.com/hc/en-us/articles/8357757911834-Setting-an-advanced-AI-agent-as-the-default-responder-for-a-messaging-channel).
    4. Save.

    Only channels enabled here are routed to OpenCX. Anything you leave off keeps Zendesk's default routing (usually straight to the Agent Workspace).

    <Tip>
      **Roll out gradually with a test channel.** Don't flip every production WhatsApp number and your live Web Widget over to the AI agent on day one. Add a single low-stakes channel first — for example a dedicated test WhatsApp number, a sandbox Messenger page, or a staging copy of your Web Widget — and enable only that one in the Marketplace. Run real conversations through it for a few days, watch the [Inbox](https://platform.open.cx/inbox) and your handoff rate, then expand to the rest of your channels once you're happy.
    </Tip>
  </Step>

  <Step title="Set Conversation control to Release control">
    The previous step makes OpenCX the *first* responder. This step makes sure OpenCX *takes back* the conversation after a human agent solves the ticket — otherwise repeat customers stay routed to Zendesk's Agent Workspace or `zd-answerBot` instead of the AI.

    `Conversation control` is an **account-wide Sunshine Conversations switchboard setting** — not a per-bot setting. It lives on the Messaging setup page, not inside the OpenCX marketplace bot entry.

    1. In Zendesk Admin Center, go to **Channels → Messaging and social → Messaging**, then open your messaging configuration. (The direct URL is subdomain-scoped: `https://<your-subdomain>.zendesk.com/admin/channels/messaging_and_social/messaging/setup`.)
    2. Expand the **Conversation control** section.
    3. Select **Release control**.
    4. Save.

    <Warning>
      **`Release control` is required for the per-channel default responder to take effect on handback.** With the default `Pass control`, when an agent solves+closes a ticket, Sunshine `passControl`'s the conversation to whatever `nextSwitchboardIntegrationId` is wired on the Agent Workspace integration — usually Zendesk's own `zd-answerBot`. With `Release control`, Sunshine clears the active integration on close, and the customer's next message gets re-assigned via the per-channel `defaultResponder` you set in the previous step (= OpenCX). This is the difference between "AI takes back" and "answer bot intercepts."

      Sources:

      * Zendesk's [About Sunshine Conversations in Zendesk Suite](https://support.zendesk.com/hc/en-us/articles/5514406080538) — section *"Configuring conversational control"*: *"Expand the Conversation control section and select your control option."*
      * Zendesk's [Setting an advanced AI agent as the default responder for a messaging channel](https://support.zendesk.com/hc/en-us/articles/8357757911834-Setting-an-advanced-AI-agent-as-the-default-responder-for-a-messaging-channel) — *"The Conversation control setting must be set to **Release control** for per-channel responders to work."*
    </Warning>
  </Step>

  <Step title="Shorten the Solved→Closed window (recommended)">
    Sunshine only hands control back to OpenCX when a Zendesk ticket transitions from **Solved** to **Closed** — not on Solved alone. By default Zendesk waits **4 days** between the two. Until close fires, any customer who returns inside that window stays routed to the Agent Workspace, not the AI.

    To make handback near-instant, do **one** of:

    * **Edit the built-in automation:** in [**Admin Center → Objects and rules → Business rules → Automations**](https://admin.zendesk.com/objects-rules/rules/automations), open `Close ticket 4 days after status is set to solved` and drop the timeframe to \~1 hour (or whatever close-window your team needs for re-opens).
    * **Add a close-on-solve trigger:** create a trigger that closes any ticket whose status changes to Solved. Handback then fires the instant an agent solves.

    Reference: [Managing conversation handoff and handback](https://support.zendesk.com/hc/en-us/articles/4408824482586-Managing-conversation-handoff-and-handback) — section *"Modifying the time between the solved and closed states"*.

    <Info>
      Skipping this step doesn't break the integration — it just means returning customers within the close window land on the Agent Workspace instead of the AI. If your reps and customers are fine with re-engaging via the live agent for a few days post-solve, the default 4-day automation is acceptable.
    </Info>
  </Step>

  <Step title="Verify end to end">
    Run a full handoff + handback cycle on a channel you enabled.

    1. **Handoff:** send a test message, request a human, confirm the conversation appears in the Zendesk Agent Workspace as a live chat. Reply from Agent Workspace and confirm it lands back on the original channel within a couple of seconds.
    2. **Solve and close:** solve the ticket from Agent Workspace, then close it (manually, or wait for your trigger / shortened automation from the previous step to fire).
    3. **Handback:** from the same end user, send a fresh message on the same channel. Confirm the AI responds — not the live agent and not Zendesk's `zd-answerBot`.

    <Tip>
      To pinpoint a routing failure on step 3, inspect the inbound webhook payload in [Admin Center → Apps and integrations → Conversations API → Webhooks → Activity](https://admin.zendesk.com/apps/integrations/apis/conversations-api). The `activeSwitchboardIntegration.name` field should be `opencx`. If it's `zd-answerBot`, your **Conversation control** is still on `Pass control` — re-check the previous step (set on the Messaging setup page, not the bot entry). If it's `zd-agentWorkspace`, the prior ticket hasn't transitioned from Solved to Closed yet — re-check the Solved→Closed window step.
    </Tip>

    If any step fails, jump to [Troubleshooting](/integrations/zendesk/troubleshooting#messaging-sunshine-issues).
  </Step>
</Steps>

## Sunshine channels handle off as live chats, not tickets

For channels routed through Sunshine — WhatsApp, Messenger, Instagram, web chat, SMS, and phone — handoff does **not** create a Zendesk ticket. The conversation appears in the Agent Workspace as a live chat. Ticket-based behavior (AI Fields auto-fill, tag application, agent-reply sync) described on the [Ticketing API](/integrations/zendesk/ticketing-api) page applies to email only.

## Turn on AI agent tickets if you want ticket ids before handoff

By default, an AI-handled messaging conversation has **no Zendesk ticket** until it's handed off to a human. Zendesk creates the ticket at escalation, and that's the moment a ticket id appears in the OpenCX [Inbox](https://platform.open.cx/inbox) sidebar. A conversation the AI resolves on its own never gets a ticket — so its ticket id in OpenCX stays empty. With the default configuration that's expected, not a bug.

If you want **every** conversation — including AI-resolved ones — to have a Zendesk ticket and a ticket id in OpenCX, turn on Zendesk's **AI agent tickets** feature:

1. In Zendesk, go to **Admin Center → Channels → Messaging and social → Messaging** and click **Manage settings**.
2. Expand **AI agent conversations as tickets in Agent Workspace** and turn it on.
3. Save.

With the setting on, Zendesk creates a read-only ticket from the first message of every AI conversation (it becomes a regular, editable ticket at handoff), and OpenCX stamps its ticket id on the session automatically — your reps also get full visibility into ongoing AI conversations from the Agent Workspace.

<Info>
  Zendesk turned AI agent tickets on by default for all accounts on **May 4,
  2026** — but accounts using Zendesk's own **AI agents - Advanced** add-on are
  exempt and may still have it off. If your AI-only conversations aren't
  producing tickets, check the setting. References: [Understanding AI agent
  tickets for AI agent–only
  conversations](https://support.zendesk.com/hc/en-us/articles/9204149016346-Understanding-AI-agent-tickets-for-AI-agent-only-conversations),
  [general availability
  announcement](https://support.zendesk.com/hc/en-us/articles/9727051305498-Announcing-the-general-availability-of-AI-agent-conversations-as-tickets-in-Support-and-Agent-Workspace),
  [default-on
  schedule](https://support.zendesk.com/hc/en-us/articles/10143404078234-Announcing-AI-agent-tickets-turned-on-by-default-for-specific-Pods).
</Info>

## WhatsApp templates sent from Zendesk show up in the session

When your team sends WhatsApp templates through Zendesk messaging — an offer, a reminder, a follow-up — and the customer replies, the templates they received in the last three days appear in the OpenCX session ahead of their reply, both in the [Inbox](https://platform.open.cx/inbox) and in the AI agent's context. The AI answers knowing which offer or question the customer is responding to, instead of greeting them as if the conversation started with their reply.

Templates Zendesk could not render as text (it stores them as "WhatsApp template (This message can only be displayed in WhatsApp)") are left out, as are templates sent more than three days before the reply. These entries are context only: they don't count as an agent reply, don't hand the session off, and are never sent back to Zendesk.

## Rotating Legacy Sunshine credentials

OAuth has no App key to rotate. For a Legacy connection, create a new App key in Zendesk, paste it into OpenCX, then delete the old key. The <Tooltip>webhook signing key</Tooltip> is unaffected by App key rotation.

## Disconnecting

To stop routing conversations to the AI, remove OpenCX from the channels in Zendesk's **AI Agents** admin (un-select the channels you enabled in *Pick the channels OpenCX should answer on*, or clear it as the default responder). Active conversations finish out on their current channel; no data is deleted from Zendesk.

For OAuth, open **Settings → Integrations → Zendesk → Messaging → OAuth**, click **Disconnect**, and type `DELETE`. This revokes and removes only the OAuth connection and its provisioned webhook; Legacy App credentials remain available. Removing the Marketplace bot in Zendesk also disconnects OpenCX through Zendesk's verified uninstall callback.

For Legacy authorization, delete the webhook in Conversations API admin to cut delivery, then remove or replace the stored App credentials through the Legacy panel.

***

## Related Documentation

<CardGroup>
  <Card title="Channels" icon="grid-2" href="/integrations/zendesk/channels/widget">
    Per-channel implementation details for Widget, WhatsApp, SMS, Phone, and
    Email.
  </Card>

  <Card title="Ticketing API" icon="envelope" href="/integrations/zendesk/ticketing-api">
    The companion path for email handoff.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/zendesk/troubleshooting">
    Agent Workspace not receiving messages, duplicate users.
  </Card>
</CardGroup>


# Zendesk Telephony
Source: https://docs.open.cx/integrations/zendesk/telephony

Connect Zendesk Talk and OpenCX phone agents in both directions — inbound calls forwarded from Zendesk Talk into OpenCX, and outbound transfers from OpenCX into Zendesk via SIP-IN.

OpenCX phone agents and Zendesk Talk integrate in two directions, each with its own setup. **Inbound** uses standard Zendesk Talk call forwarding to an OpenCX phone number. **Outbound transfers** ride over Zendesk's [SIP-IN line](https://support.zendesk.com/hc/en-us/articles/8397091234586) so the call lands directly inside the Agent Workspace with a recoverable ticket id.

This page covers both. Pick the section that matches the leg you're configuring.

## Receiving inbound calls (Zendesk Talk → OpenCX)

Use this when you want the OpenCX AI phone agent to answer first — for triage, qualification, deflection, or full automation — before optionally handing the call to a human in Zendesk.

Zendesk Talk **does not** support SIP-OUT or custom SIP headers when forwarding outbound. The only supported transport from Zendesk Talk to an external system is plain PSTN call forwarding to a regular phone number, which strips all metadata. To work around this, OpenCX subscribes a webhook to Zendesk's `ticket.created` event and uses it to correlate the new phone-channel ticket back to the OpenCX phone session created when the call lands on our SIP. The matched ticket id is stamped on the OpenCX session, and the ticket's requester is fetched to enrich the OpenCX contact with verified name, email, phone, and any configured Zendesk user/organization attributes.

### Prerequisites

* A phone number provisioned and verified in OpenCX. See [phone setup](/channels/phone) if you haven't done that yet.
* The Zendesk integration connected — see the [Zendesk overview](/integrations/zendesk/overview). Saving the Zendesk connection auto-provisions the `ticket.created` event-subscription webhook against your account; no manual webhook or trigger setup is required.

### Step 1 — Connect Zendesk in OpenCX

Open the OpenCX dashboard → **Integrations → Zendesk → Connect**, paste your subdomain + API token + agent email, and save. On save OpenCX upserts an event-subscription webhook named `opencx-messaging-ticket-link` in your Zendesk account, pointing at the OpenCX receiver and subscribed to `messaging_ticket.message_added`, `ticket.status_changed`, and `ticket.created`. The webhook is idempotent — re-saving the connection is safe and won't disturb any of your other webhooks, triggers, or automations.

### Step 2 — Forward the call to OpenCX

Configure your Zendesk Talk number (or IVR / call queue branch) to forward to your verified OpenCX phone number using Zendesk Talk's standard forwarding flow. Nothing OpenCX-specific is required at this step — the auto-provisioned webhook carries the metadata; the call itself rides over PSTN.

### Troubleshooting

<AccordionGroup>
  <Accordion title="`zendesk_ticket_id` never lands on the OpenCX session">
    Open the OpenCX-managed webhook in **Admin Center → Apps and integrations → Webhooks → `opencx-messaging-ticket-link` → Activity** and confirm `ticket.created` deliveries are firing and responding `200`. If deliveries are missing entirely, re-save the Zendesk connection in the OpenCX dashboard — the provisioner runs again on each save and is safe to re-trigger. If deliveries are firing but the OpenCX session is not getting stamped, double-check that the inbound caller's phone digits match the contact phone OpenCX recorded for the call (PSTN forwarding occasionally strips/rewrites the `From` number depending on your carrier configuration).
  </Accordion>

  <Accordion title="`opencx-messaging-ticket-link` webhook doesn't appear in Zendesk">
    The provisioner is best-effort — a transient Zendesk API outage at settings-save time will be logged but won't fail the save. Re-save the Zendesk connection in the OpenCX dashboard to retry.
  </Accordion>
</AccordionGroup>

## Transferring calls from OpenCX to Zendesk (SIP-IN)

Use this when the OpenCX AI agent has triaged the call and needs to hand it to a human agent in Zendesk Talk. The transfer rides over [Zendesk SIP-IN](https://support.zendesk.com/hc/en-us/articles/8397091234586), which means the call shows up natively inside the Agent Workspace as a Zendesk Talk call — the agent picks it up, sees the caller ID, and (when the ticket id is known) can correlate the leg back to the ticket OpenCX received the call against.

### How it works

OpenCX initiates a SIP outbound bridge to your Zendesk SIP-IN line and attaches the original caller's phone as the `From` and the originating Zendesk ticket id (when known) as `X-Zendesk-Ticket-Id` — Zendesk SIP-IN's [documented header](https://support.zendesk.com/hc/en-us/articles/8397091234586) for binding the inbound SIP leg to an existing voice ticket. Without it, Zendesk Talk creates a brand-new ticket for the inbound INVITE and the leg gets orphaned from the originating ticket. Every transferred leg carries:

* `X-Zendesk-Ticket-Id` — the originating Zendesk ticket id, **only** when:
  * the active OpenCX session has a ticket id stamped on it (from the inbound flow above), and
  * the destination is a SIP URI (PSTN-only destinations don't carry the header).
* `X-OPENCX-SESSION-ID` — the OpenCX phone session id.
* `X-OPENCX-AGENT-ID` — the OpenCX AI agent id.
* `X-OPENCX-TRANSFER` — `true`.
* `X-OPENCX-CONTACT-ID` — the OpenCX contact id (when resolved).

The originating caller's phone number is preserved as the `From` so Zendesk Talk renders the correct caller ID inside the Agent Workspace.

### Prerequisites

* A configured Zendesk SIP-IN line — follow the [Zendesk SIP-IN setup docs](https://support.zendesk.com/hc/en-us/articles/8397091234586). You'll end up with a SIP URI of the form `sip:<your-line>@<subdomain>.zendesk.sip.twilio.com`.
* An OpenCX AI phone agent with at least one transfer destination configured.

### Step 1 — Add the Zendesk SIP-IN URI as a transfer destination

In the OpenCX dashboard, open the AI phone agent's settings and add a new **Transfer destination** of type **SIP**. Paste the SIP URI from your Zendesk SIP-IN line as the destination URI, and give it a label your AI agent will recognize ("Zendesk human agent", "Tier 2", etc.).

The AI agent then picks this destination at runtime when the conversation logic — your prompt, knowledge, or tools — decides to hand off.

### Step 2 — (Optional) Confirm ticket re-association on the Zendesk side

If you've also configured the inbound flow above, every transfer leg will carry `X-Zendesk-Ticket-Id` whenever the ticket id was successfully stamped on the OpenCX session. Zendesk SIP-IN reads the header natively: the inbound leg is associated with the existing voice ticket (which must have been created with `via_id: 34` — Zendesk Talk's own inbound calls always satisfy this) instead of spawning a duplicate. No Zendesk-side trigger or app is required.

### What does *not* work

* **PSTN-only transfers** (carrier-issued REFER to a regular phone number) won't reach Zendesk Talk natively — Zendesk Talk only accepts inbound SIP via SIP-IN. If your transfer destination is a regular phone number rather than a SIP URI, the call will route through your carrier as a normal outbound, not through Zendesk.
* **Zendesk SIP-OUT**. Zendesk Talk does not support SIP-OUT, which is why the inbound direction has to use PSTN forwarding plus the `ticket.created` webhook.

### Troubleshooting

<AccordionGroup>
  <Accordion title="Transfer connects but Zendesk shows the wrong caller ID">
    Double-check that the OpenCX session knows the caller's phone number. SIP transfers use the original caller's phone as the `From` — if the inbound leg arrived without caller ID (anonymous, blocked, or stripped by an upstream IVR), Zendesk will see the OpenCX-side `From` instead. There's no workaround for an anonymous caller.
  </Accordion>

  <Accordion title="Transfer fails to connect">
    Confirm the SIP-IN URI is correct and reachable from your OpenCX SIP egress IP range — Zendesk SIP-IN requires IP allow-listing on the Zendesk side. See the Zendesk SIP-IN docs for the current allow-list values.
  </Accordion>
</AccordionGroup>

## Next steps

* [AI Phone Support in the Zendesk Agent Workspace](/integrations/zendesk/channels/phone) — for the messaging-style handoff (Sunshine Conversations) instead of a SIP transfer.
* [Phone channel setup](/channels/phone) — to provision the OpenCX DID that receives forwarded calls.
* [Zendesk overview](/integrations/zendesk/overview) — for ticketing-side configuration.


# Ticketing API
Source: https://docs.open.cx/integrations/zendesk/ticketing-api

Connect Zendesk so email handoffs become tickets your reps work from the inbox they already live in.

The Ticketing API path wires OpenCX into Zendesk's standard <Tooltip>support API</Tooltip>. Use it for **email** — the async channel where every handoff should become a trackable <Tooltip>ticket</Tooltip>. Chat, SMS, WhatsApp, phone, and social belong on [Sunshine Conversations](/integrations/zendesk/sunshine-conversations) instead.

<ZendeskTicketingFlow />

<Info>
  Setup takes about 15 minutes. You need a Zendesk admin role on both sides — your OpenCX organization and your Zendesk account.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Zendesk plan with API access" icon="circle-check">
    Suite Team or higher, or Support Professional. Suite Growth and above is recommended so you can use <Tooltip>triggers</Tooltip> for webhook delivery.
  </Accordion>

  <Accordion title="Admin access in Zendesk" icon="user-shield">
    OAuth requires an agent or admin who can authorize the OpenCX global OAuth client. You also need permission to create a webhook and trigger in [Zendesk Admin Center](https://admin.zendesk.com). Legacy setup additionally requires permission to generate an API token.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="key">
    Required to save integration settings in [Settings → Integrations](https://platform.open.cx/settings/integrations).
  </Accordion>
</AccordionGroup>

## Choose authorization

Open [**Settings → Integrations**](https://platform.open.cx/settings/integrations), select **Zendesk → Ticketing**, then choose:

* **OAuth — recommended:** authorize OpenCX in Zendesk. No API token is stored or rotated.
* **Legacy credentials:** enter an admin email and API token. Existing installations continue to work and can switch to OAuth without losing their legacy fallback until it is removed.

## OAuth setup (recommended)

<Steps>
  <Step title="Choose Ticketing OAuth">
    In OpenCX, open **Settings → Integrations → Zendesk → Ticketing → OAuth**.
  </Step>

  <Step title="Enter your Zendesk subdomain">
    Enter only the `acme` part of `acme.zendesk.com`, then click **Continue to Zendesk**. Do not include `https://` or `.zendesk.com`.
  </Step>

  <Step title="Authorize OpenCX">
    Sign in to the matching Zendesk account, review the requested Support API access, and click **Allow**. Zendesk returns you to OpenCX, which verifies the account and displays **Connected**.

    <Warning>
      The Zendesk account you authorize must match the subdomain you entered. OpenCX rejects cross-account callbacks rather than attaching one customer's OAuth grant to another customer.
    </Warning>
  </Step>

  <Step title="Register the reply webhook and trigger">
    Back in the OAuth panel, copy the signed **Reply webhook URL** and open its trigger instructions. In Zendesk, create a `POST` JSON webhook with no additional authentication, then create a trigger with:

    * **Meet ANY:** Ticket is Created; Ticket is Updated.
    * **Meet ALL:** Comment is Present (public).
    * **Action:** Notify active webhook using the OpenCX webhook.
    * **JSON body:**

    ```json theme={"dark"}
    {
      "ticketId": "{{ticket.id}}",
      "event_type": "new_comment"
    }
    ```

    OAuth authenticates OpenCX's calls to Zendesk; the trigger is still required for Zendesk to deliver public agent replies back to OpenCX.
  </Step>

  <Step title="Verify end to end">
    Escalate a test email, confirm the Zendesk ticket has the `opencx` tag, then post a public agent reply. The reply should appear on the matching OpenCX session. Internal notes must remain private.
  </Step>
</Steps>

## Legacy API token setup

<Steps>
  <Step title="Generate a Zendesk API token">
    In Zendesk, open [**Admin Center → Apps and integrations → APIs → Zendesk API → API Tokens → Add API token**](https://support.zendesk.com/hc/en-us/articles/4408889192858-Managing-API-token-access-to-the-Zendesk-API).

    1. Toggle **Token access** on.
    2. Click **Add API token**.
    3. Label it `OpenCX` (or anything recognizable).
    4. **Copy the token immediately** — Zendesk hides it after you close the dialog.

    <Warning>
      The token is bound to the user whose email you provide in the next step. If that user is deactivated or loses permission, the integration stops working.
    </Warning>
  </Step>

  <Step title="Open Zendesk Ticketing in OpenCX">
    In OpenCX, go to [**Settings → Integrations**](https://platform.open.cx/settings/integrations), find **Zendesk**, and click **Zendesk Ticketing**.
  </Step>

  <Step title="Enter your credentials">
    | Field | Value |
    | - | - |
    | **Subdomain** | The `acme` part of `acme.zendesk.com`. Do not include `.zendesk.com` or `https://`. |
    | **Email** | The admin email that owns the API token. |
    | **API Token** | The token you just copied. |
    | **Default Agent ID** | Required. The numeric Zendesk user ID used as the fallback assignee when no routing rule applies. To find it: in Zendesk, open the agent's profile page (**Admin Center → People → Team members → click the agent**). The ID is the number at the end of the URL — e.g. in `https://your-subdomain.zendesk.com/agent/users/1234567890/tickets/requested`, the Default Agent ID is `1234567890`. |

    Click **Test & Save**. OpenCX hits the Zendesk API with your credentials before persisting — a wrong subdomain or token returns an error and nothing saves.
  </Step>

  <Step title="Copy your webhook URL">
    After saving, OpenCX displays a **Webhook URL** unique to your organization. Keep this tab open — you'll paste it into Zendesk next.

    <Warning>
      The webhook URL is signed and secret. Anyone who has it can post events into your OpenCX session pipeline. Treat it like a password.
    </Warning>
  </Step>

  <Step title="Register the webhook in Zendesk">
    In Zendesk, follow [Zendesk's guide to creating a webhook](https://support.zendesk.com/hc/en-us/articles/4408839108378-Creating-webhooks-to-interact-with-third-party-systems) to open **Admin Center → Apps and integrations → Webhooks**, then click **Create webhook → Trigger or automation**.

    | Field | Value |
    | - | - |
    | **Name** | `OpenCX` |
    | **Endpoint URL** | Paste the OpenCX webhook URL. |
    | **Request method** | `POST` |
    | **Request format** | `JSON` |
    | **Authentication** | `None` — the URL is already signed. |

    Save the webhook.
  </Step>

  <Step title="Create the trigger that fires the webhook">
    Follow [Zendesk's guide to creating a trigger](https://support.zendesk.com/hc/en-us/articles/4408886797466-Creating-ticket-triggers-for-automatic-ticket-updates-and-notifications) to open **Admin Center → Objects and rules → Triggers** and click **Create trigger**.

    Configure:

    * **Trigger name:** `OpenCX webhook` (or anything recognizable).
    * **Category:** pick an existing category such as `Notifications`, or create a new one (e.g. `OpenCX`).
    * **Conditions → Meet ANY of:** `Ticket → Is → Created`; `Ticket → Is → Updated`.
    * **Conditions → Meet ALL of:** `Comment → Is → Present (public)`.

    <Warning>
      You need **both** `Created` and `Updated` under **Meet ANY of**. `Is → Updated` alone does not fire on ticket creation, so brand-new tickets would never reach OpenCX.
    </Warning>

    * **Actions → Notify by → Active webhook**, then select `OpenCX` from the dropdown.
    * **JSON body** — paste exactly:

    ```json theme={"dark"}
    {
      "ticketId": "{{ticket.id}}",
      "event_type": "new_comment"
    }
    ```

    <Warning>
      Both keys are required and case-sensitive: `ticketId` (camelCase) and `event_type` set to the literal string `new_comment`. OpenCX rejects any other shape with `400 ticketId is required`. Do **not** put the comment text in the body — OpenCX fetches the comment from Zendesk itself. Internal notes never reach the customer; with **Let the AI read internal notes** on, the AI gets them as private context only.
    </Warning>

    Click **Create trigger** and save.
  </Step>

  <Step title="Verify end to end">
    Send a test email to an address you have connected to OpenCX email handoff. Escalate the conversation. Within a few seconds:

    1. A ticket appears in Zendesk, tagged `opencx`.
    2. Reply publicly from Zendesk.
    3. The reply appears as an agent message on the matching session in your [OpenCX Inbox](https://platform.open.cx/inbox).

    <Info>
      **Every OpenCX ticket is traceable back to its session.** The session UUID is written to the ticket's `external_id`, and the first comment includes a **View session in OpenCX** link that opens the full AI reasoning, tool calls, and transcript in your inbox. Filter Zendesk views by `external_id` or any `opencx_*` tag described below.
    </Info>

    If any step fails, jump to [Troubleshooting](/integrations/zendesk/troubleshooting).
  </Step>
</Steps>

## How handoff lands in Zendesk

```mermaid theme={"dark"}
flowchart LR
  A[Contact message] --> B{AI can resolve?}
  B -- Yes --> C[AI replies on channel]
  B -- No --> D[Handoff]
  D --> E[Create or update Zendesk ticket]
  E --> F[Rep replies publicly in Zendesk]
  F --> G[Reply syncs back to contact on the original channel]
```

When <Tooltip href="/handoff/introduction">handoff</Tooltip> triggers, OpenCX does the following in Zendesk:

1. Looks up the contact by email. If not found, creates a Zendesk user with the contact's email and name.
2. Creates a ticket with the session ID as <Tooltip>`external_id`</Tooltip>, the conversation summary as the description, and the full transcript appended as the first comment.
3. Applies tags (see [Tags OpenCX applies](#tags-opencx-applies) below) so your views and triggers can filter by mode, channel, sentiment, and language.
4. Auto-fills any custom fields you've mapped (see [AI Fields](#ai-fields) below).
5. Assigns to your **Default Agent ID** if configured; otherwise leaves unassigned for Zendesk routing to handle.

<Note>
  The session is linked to the ticket by `external_id`. If the same contact re-engages before the ticket is closed, OpenCX appends to the existing ticket instead of opening a new one.
</Note>

### Create a ticket only on handoff

By default OpenCX only creates a ticket when the AI escalates. If you want every conversation to create a ticket up front (for audit or SLA reasons), reach out to support — this flag is set per organization.

<Note>
  With this flag on, tickets created at handoff are assigned to your **Default Agent Group** (if set) rather than the **Default Agent ID** — the individual-agent assignment in step 5 above applies only to the standard, ticket-created-early flow.
</Note>

### Create tickets for email sessions

Email sessions only produce a ticket at handoff unless you turn this on. Enable **Create tickets for email sessions** at [**Settings → Ticketing**](https://platform.open.cx/settings/ticketing) and every email session opens a Zendesk ticket from the customer's first message, with the rest of the conversation kept on it.

The customer's first email becomes an **internal note** on the Zendesk ticket. The customer remains the requester, and the email subject and receiving inbox tag are preserved. Later customer emails and your team's replies continue to follow the existing message-syncing behavior.

<Note>
  This setting does **not** change who sends the reply to the customer — that stays governed by the outbound strategy on the connected inbox. If OpenCX sends the reply, the ticket receives it as an internal note so the customer is never emailed twice.
</Note>

Applies to new sessions only: email sessions already open when you enable it keep running without a ticket. Leave it off and nothing changes — this is the behavior every organization has today.

Only sessions that start in OpenCX are mirrored. Email tickets that already exist in Zendesk and reach OpenCX through the Zendesk integration are never written back to — the customer's email is already on that ticket.

## Rep replies sync back

When a rep posts a **public** reply in Zendesk, the webhook fires and OpenCX:

1. Matches the ticket to the original session using `external_id`.
2. Sends the reply to the contact on the original channel — email, SMS, WhatsApp, web widget, etc.
3. Marks the session as having an active human agent so the AI stops auto-responding.

<Tooltip>Internal notes</Tooltip> your agents write never trigger outbound messages, so your reps can take private notes in Zendesk freely. By default the AI doesn't see them either; turn on **Let the AI read internal notes** in Settings, Ticketing to give them to the AI as private context. With that setting on, a private comment from the requester themselves counts as their message and gets an answer.

<Warning>
  Only **public** comments sync. If a rep accidentally posts to the wrong ticket, the message still reaches that ticket's linked contact. Treat Zendesk tickets as customer-visible threads.
</Warning>

## AI Fields

Map Zendesk <Tooltip>custom fields</Tooltip> to AI-generated values so triage, routing, and reporting work on day one. Configure at [**Settings → Ticketing**](https://platform.open.cx/settings/ticketing) under **Auto fill Zendesk fields**.

<Steps>
  <Step title="Pick a Zendesk field">
    OpenCX loads every custom field on your Zendesk account. Pick one — dropdown (<Tooltip>tagger</Tooltip>) and free-text fields are supported.
  </Step>

  <Step title="Describe what the AI should fill">
    Write a short description of what the field represents. For dropdowns, OpenCX picks from existing options only. For text, OpenCX writes a short value.

    Example description for a **Reason** dropdown: *"The primary reason the contact is writing. Pick the closest match from the allowed values."*
  </Step>

  <Step title="Enable">
    Toggle the mapping on. The next ticket OpenCX creates (or updates on handoff) includes the auto-filled value.
  </Step>
</Steps>

<Tip>
  Keep descriptions short and concrete. Fields with vague descriptions ("customer feedback") produce vague values.
</Tip>

<Note>
  OpenCX only fills fields that are still empty. A value already on the ticket or on the requester's profile, whether your agents set it or OpenCX filled it on an earlier handoff, is never replaced. To have OpenCX fill a field again, clear it in Zendesk first.
</Note>

## Tags OpenCX applies

| Tag | When |
| - | - |
| `opencx` | Always, on any ticket OpenCX creates or writes to. |
| `opencx_autopilot` | The AI was in autopilot (resolved or handed off without a rep present). |
| `opencx_assist_mode` | The AI posted an internal note on an agent-owned ticket (Assist Mode — a [discouraged fallback](/integrations/zendesk/troubleshooting#assist-mode-doesnt-post-suggestions)). |
| `opencx_handedoff` | The AI escalated to a human rep. |
| `opencx_channel_<name>` | The source channel — `email`, `whatsapp`, `sms`, `web`, `phone`. |
| `opencx_sentiment_<value>` | Detected sentiment on handoff — `happy`, `neutral`, `negative`. |
| `opencx_language_<code>` | Detected conversation language. |
| `opencx_ticket_created_on_handoff` | Applied when the ticket was created at handoff (vs updated on a returning contact). |

Use these tags in Zendesk views, triggers, and reports.

## Rotating Legacy credentials

OAuth access is refreshed automatically and has no API token to rotate. For a Legacy connection, regenerating the Zendesk API token does not affect the webhook — the webhook URL is signed with a separate key. To rotate:

1. Create a new token in Zendesk.
2. Paste it into [Settings → Integrations → Zendesk](https://platform.open.cx/settings/integrations).
3. Delete the old token in Zendesk.

## Disconnecting

For OAuth, open **Settings → Integrations → Zendesk → Ticketing → OAuth**, click **Disconnect**, and type `DELETE`. This revokes and removes only the OAuth connection; complete Legacy credentials remain available. Delete or deactivate the Zendesk trigger and webhook as well if you want public-comment delivery to stop. Tickets created while the integration was active remain untouched.

For Legacy authorization, remove or replace the saved credentials through the Legacy panel. Deactivating the Zendesk trigger and webhook stops new inbound events immediately.

***

## Related Documentation

<CardGroup>
  <Card title="AI Email in Zendesk" icon="envelope" href="/integrations/zendesk/channels/email">
    Per-channel implementation details for email handoff.
  </Card>

  <Card title="Sunshine Conversations" icon="messages" href="/integrations/zendesk/sunshine-conversations">
    The path for chat, SMS, WhatsApp, phone, and social channels.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/zendesk/troubleshooting">
    Webhook 4xx, trigger not firing, credentials failing.
  </Card>
</CardGroup>


# Zendesk troubleshooting
Source: https://docs.open.cx/integrations/zendesk/troubleshooting

Debug Zendesk connection, webhook, ticket creation, agent reply sync, and article sync issues.

Before debugging, have this ready:

* Your Zendesk <Tooltip>subdomain</Tooltip> and the admin email used for the <Tooltip>API token</Tooltip>.
* A specific <Tooltip>session ID</Tooltip> (from [Inbox](https://platform.open.cx/inbox)) or Zendesk ticket ID where the problem shows.
* The webhook URL shown in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Zendesk.

<Tip>
  Re-run **Verify** in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Zendesk as your first step. Most issues are credential or webhook related.
</Tip>

<Info>
  **Fastest path to root cause:** filter Zendesk tickets by the `opencx_channel_*`, `opencx_sentiment_*`, or `opencx_handedoff` tags to scope the issue, then click **View session in OpenCX** in the first comment of the failing ticket. That link opens the full AI reasoning, tool calls, and handoff event — far faster than log-diving.
</Info>

## Common scenarios

Jump to the symptom that matches what you're seeing.

### **"Failed to verify credentials" on save**

<Tooltip>Likely cause</Tooltip>: wrong subdomain format, expired token, or API access disabled.

**Fix:** use just the subdomain part (`acme`, not `acme.zendesk.com`). Regenerate the token in [Zendesk Admin Center](https://admin.zendesk.com/apps/integrations/apis/zendesk-api). Confirm **Token access** is toggled on.

### **"Failed to verify credentials" on Sunshine Messaging save**

<Tooltip>Likely cause</Tooltip>: wrong key type (Integration key, not App key), or wrong App ID.

**Fix:** confirm the Key ID starts with `app_`. If it doesn't, delete the key and create a new one from the **Conversations API** section of Admin Center — not from inside a specific integration. Re-copy the App ID from the top of that same page.

### **Handoff runs but no ticket appears in Zendesk**

<Tooltip>Likely cause</Tooltip>: contact has no email, or the Zendesk user behind the API token lacks permission to create users and tickets.

**Fix:** confirm the OpenCX contact has an email. Confirm the token's Zendesk user is an <Tooltip>admin</Tooltip> or an agent with full access.

### **Agent public replies don't reach the contact**

<Tooltip>Likely cause</Tooltip>: webhook missing, trigger misconfigured, or wrong event subscription.

**Fix:** in [Zendesk Admin Center → Triggers](https://admin.zendesk.com/objects-rules/rules/triggers), confirm the condition is `Ticket is Updated` with a public comment present, and the action posts to the OpenCX webhook URL. <Tooltip>Retry the failed delivery</Tooltip> from the webhook's activity log.

### **Internal notes reaching the contact**

<Tooltip>Likely cause</Tooltip>: this shouldn't happen — internal notes are filtered on OpenCX's side.

**Fix:** none on your side. OpenCX reads comments from Zendesk directly and syncs only public replies; internal notes never reach the contact. If you do see a note leak, open a support request with the ticket ID and the session ID.

### **Duplicate tickets for the same conversation**

<Tooltip>Likely cause</Tooltip>: handoff fires multiple times before the first ticket's <Tooltip>`external_id`</Tooltip> links to the session.

**Fix:** none on your side — dedup is automatic once the link exists. If you see this consistently, open a support request with two example session IDs.

### **AI fields show blank on the ticket**

<Tooltip>Likely cause</Tooltip>: mapping disabled or description too vague.

**Fix:** check [Settings → Ticketing](https://platform.open.cx/settings/ticketing) → Auto fill Zendesk fields. Enable the mapping. Tighten the description with <Tooltip>concrete examples</Tooltip>.

### **AI fields keep an old value**

<Tooltip>Likely cause</Tooltip>: the field already had a value when OpenCX filled the ticket.

**Fix:** none needed — this protects values your agents set. To have OpenCX fill the field again, clear it in Zendesk before the next handoff or close.

### **Help Center articles not appearing in AI answers**

<Tooltip>Likely cause</Tooltip>: initial sync still running, or articles are <Tooltip>internal</Tooltip>.

**Fix:** open [Data Sources](https://platform.open.cx/data-sources), wait for sync to complete. Check article visibility in Zendesk — published + no segment restriction is required for public answers.

### **Webhook returns 4xx in Zendesk's activity log**

<Tooltip>Likely cause</Tooltip>: stale webhook URL, or a malformed trigger body.

**Fix:** first confirm the trigger's JSON body is exactly `{ "ticketId": "{{ticket.id}}", "event_type": "new_comment" }` — a missing or misspelled `ticketId`/`event_type` (e.g. the old `ticket_id`) returns `400 ticketId is required`. If the body is correct, copy the current URL from [Settings → Integrations](https://platform.open.cx/settings/integrations) → Zendesk and update the webhook endpoint in Zendesk.

### **Webhook returns 5xx in Zendesk's activity log**

<Tooltip>Likely cause</Tooltip>: OpenCX couldn't match the ticket to a session.

**Fix:** confirm the ticket was created by OpenCX (it carries the `opencx` tag and an `external_id`). Tickets created directly in Zendesk have no linked session, so their comments have nowhere to sync. See the [Ticketing API setup](/integrations/zendesk/ticketing-api) reference payload.

## Handoff creates a ticket but agent replies do nothing

Work through this checklist:

1. Open the ticket in Zendesk. Confirm it has tag <Tooltip>`opencx`</Tooltip> and an `external_id` set.
2. In [Zendesk Admin Center → Webhooks](https://admin.zendesk.com/apps/integrations/webhooks), open your OpenCX webhook. Check **Activity** — recent calls should return `2xx`. A `4xx` means the webhook URL is stale (re-copy from OpenCX). A `5xx` means OpenCX couldn't match the ticket to a session.
3. Confirm the <Tooltip>trigger</Tooltip> in [Admin Center → Triggers](https://admin.zendesk.com/objects-rules/rules/triggers) is active.
4. Confirm the reply was posted as **Public reply**, not **Internal note**.
5. Confirm the original contact channel is still reachable (email address valid, WhatsApp/SMS number still subscribed).

## Assist Mode doesn't post suggestions

<Warning>
  **Assist Mode is a discouraged fallback.** We recommend [autopilot](/handoff/introduction) for every new deployment — Assist exists only for teams that aren't yet ready to hand customer replies to the AI. If you're evaluating OpenCX, start with autopilot.
</Warning>

If you're already running Assist and suggestions aren't appearing, check in order:

* The ticket wasn't created by OpenCX — <Tooltip>Assist runs on rep-opened tickets only</Tooltip>.
* The ticket's topic isn't on the <Tooltip>no-assist list</Tooltip> (look for that tag).
* The AI produced an answer — look for `opencx_skipped_not_helpful_answer`, which means the AI judged its own answer incomplete and stayed quiet.
* The ticket is in a status where suggestions apply (open / pending).

<AccordionGroup>
  <Accordion title="How to enable Assist (if you must)" icon="gear">
    Assist runs on the same webhook and trigger as [Ticketing API](/integrations/zendesk/ticketing-api) — no extra credentials.

    1. Complete Ticketing API setup first.
    2. In [Settings → Autopilot](https://platform.open.cx/settings/autopilot), configure the no-assist topic list.
    3. In [Settings → Integrations](https://platform.open.cx/settings/integrations) → Zendesk Ticketing, toggle **Assist Mode** on.

    Assist posts drafts as internal notes on rep-owned tickets. Tag `opencx_assist_mode` is applied to every ticket Assist writes to. The customer never sees the draft.
  </Accordion>
</AccordionGroup>

## Messaging (Sunshine) issues

### **Handoff on WhatsApp creates a ticket instead of a chat**

<Tooltip>Likely cause</Tooltip>: Sunshine credentials missing or inactive.

**Fix:** confirm the Messaging tab in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Zendesk shows **Active**. Re-enter credentials if needed.

### **Rep reply in Agent Workspace doesn't reach WhatsApp**

<Tooltip>Likely cause</Tooltip>: webhook not registered or wrong event subscription.

**Fix:** re-register the Sunshine webhook subscribed to `conversation:message`. See [Sunshine Conversations setup](/integrations/zendesk/sunshine-conversations).

### **Second chat session from the same end user never reaches Agent Workspace**

<Tooltip>Likely cause</Tooltip>: multi-conversations not enabled on the Sunshine app.

**Fix:** turn on multi-conversations in [Admin Center → Channels → Messaging and social → Messaging → Manage settings → Multi-conversations](https://admin.zendesk.com/channels/messaging_and_social/messaging) for every Web/iOS/Android channel OpenCX answers on. Full walkthrough in the Sunshine setup — see [Turn on multi-conversations for the Sunshine app](/integrations/zendesk/sunshine-conversations#turn-on-multi-conversations-for-the-sunshine-app). Note this change is irreversible.

### **Sunshine conversation never appears as a Zendesk ticket**

<Tooltip>Likely cause</Tooltip>: working as designed — Sunshine conversations only surface as tickets after handoff to a human, unless **AI agent tickets** is turned on.

**Fix:** if you want to see AI-only conversations as tickets in the Agent Workspace before escalation, turn on **AI agent tickets** in [Admin Center → Channels → Messaging and social → Messaging → Manage settings → AI agent conversations as tickets in Agent Workspace](https://admin.zendesk.com/channels/messaging_and_social/messaging). These tickets are read-only until handoff. Zendesk turned this on by default for all accounts on **May 4, 2026**, but accounts using Zendesk's **AI agents - Advanced** add-on are exempt and may still have it off. Full reference: [Understanding AI agent tickets for AI agent–only conversations](https://support.zendesk.com/hc/en-us/articles/9204149016346-Understanding-AI-agent-tickets-for-AI-agent-only-conversations).

### **Session shows no Zendesk ticket id in the OpenCX Inbox**

<Tooltip>Likely cause</Tooltip>: no Zendesk ticket exists for the conversation yet, or the `opencx-messaging-ticket-link` event webhook is missing.

Work through this checklist:

1. **Was the conversation handed off?** If not, and **AI agent tickets** is off in Zendesk, no ticket exists — an empty ticket id is expected, not a bug. The id appears within seconds of handoff. To get ticket ids for AI-only conversations too, turn on **AI agent tickets** — see [Turn on AI agent tickets if you want ticket ids before handoff](/integrations/zendesk/sunshine-conversations#turn-on-ai-agent-tickets-if-you-want-ticket-ids-before-handoff).
2. **Does the event webhook exist?** In [Admin Center → Apps and integrations → Webhooks](https://admin.zendesk.com/apps/integrations/webhooks), look for an active webhook named `opencx-messaging-ticket-link` subscribed to [`messaging_ticket.message_added`](https://developer.zendesk.com/api-reference/webhooks/event-types/messaging-events/). If it's missing, re-save your Zendesk Messaging settings in [Settings → Integrations](https://platform.open.cx/settings/integrations) — OpenCX provisions it automatically on save, provided the **Zendesk API credentials** panel is filled in.
3. **Did the session predate the webhook?** Linking is forward-only: sessions that ended before the webhook was provisioned keep an empty ticket id. There is no retroactive backfill.

### **AI doesn't take the conversation back after a ticket is solved or closed**

<Tooltip>Likely cause</Tooltip>: one of two routing-config gaps — either the Solved→Closed transition hasn't fired yet, or the account's `Conversation control` setting isn't `Release control` so handback follows the wrong chain.

**Fix #1 — Set the account-wide Sunshine `Conversation control` to `Release control`. This is almost always the actual fix.**

`Conversation control` is an **account-wide Sunshine Conversations switchboard setting** — not a per-bot setting. It lives on the Messaging setup page, not inside the OpenCX marketplace bot entry.

In Zendesk Admin Center, go to **Channels → Messaging and social → Messaging**, open your messaging configuration (`https://<your-subdomain>.zendesk.com/admin/channels/messaging_and_social/messaging/setup`), expand the **Conversation control** section, select **Release control**, and save.

Why this matters: with the default `Pass control`, when an agent closes a ticket Sunshine `passControl`'s the conversation to whatever `nextSwitchboardIntegrationId` is wired on the Agent Workspace integration — typically Zendesk's own `zd-answerBot`, not OpenCX. With `Release control`, Sunshine clears the active integration on close, and the customer's next message gets re-assigned via the per-channel `defaultResponder` (which is OpenCX once configured per setup step 7).

References:

* Zendesk's [About Sunshine Conversations in Zendesk Suite](https://support.zendesk.com/hc/en-us/articles/5514406080538) — section *"Configuring conversational control"*.
* Zendesk's [Setting an advanced AI agent as the default responder for a messaging channel](https://support.zendesk.com/hc/en-us/articles/8357757911834-Setting-an-advanced-AI-agent-as-the-default-responder-for-a-messaging-channel) — search the article for *"Release control"*.

**Fix #2 — Make sure OpenCX is the per-channel default responder.**

Even with `Release control`, the post-handback routing only lands on OpenCX if the channel itself has OpenCX as its default responder. In Admin Center → **AI → AI agents → AI agents → Marketplace bots → OpenCX**, under **Channels**, click **Options → Assign default** for every channel you want AI on (or use **Set as default for all channels** to cover the lot). Reference: [Managing third-party bots in Admin Center](https://support.zendesk.com/hc/en-us/articles/5064149334426-Managing-third-party-bots-in-Admin-Center).

**Fix #3 — Shorten the Solved→Closed window so handback fires quickly, not in 4 days.**

Sunshine only hands control back on the **Closed** transition, not on **Solved**. By default Zendesk waits 4 days. Until then, any return message sticks with Agent Workspace.

* **Quick option:** edit the built-in automation `Close ticket 4 days after status is set to solved` in [**Admin Center → Objects and rules → Business rules → Automations**](https://admin.zendesk.com/objects-rules/rules/automations) and drop the timeframe (down to 1 hour).
* **Immediate option:** add a Zendesk trigger that closes any ticket whose status changes to Solved, so handback fires the instant an agent solves.

Reference: [Managing conversation handoff and handback](https://support.zendesk.com/hc/en-us/articles/4408824482586-Managing-conversation-handoff-and-handback) — section *"Modifying the time between the solved and closed states"*.

**Verify after the changes:** solve and close a test ticket, send a follow-up message from the same end user, and confirm the next inbound webhook arrives with `activeSwitchboardIntegration.name = opencx` (visible in the Zendesk webhook activity log or the OpenCX session timeline). If `activeSwitchboardIntegration.name` is still `zd-answerBot` or `zd-agentWorkspace`, fix #1 hasn't been applied.

### **Duplicate contact in Zendesk for the same WhatsApp number**

<Tooltip>Likely cause</Tooltip>: <Tooltip>user merge</Tooltip> skipped because the Zendesk API credentials are missing from the Messaging integration.

**Fix:** paste the same credentials you use for Ticketing into the **Zendesk API credentials** panel under the Messaging setup.

## Limits & timing

| | Value |
| - | - |
| **Webhook processing timeout** | 10 seconds |
| **Deduplication window** (agent replies, Assist suggestions) | 48 hours |
| **Help Center initial sync** | Minutes to a few hours depending on article count |
| **Help Center incremental sync** | Hourly / daily (configurable per source) |
| **Zendesk API rate limit** | Governed by your Zendesk plan (200 req/min standard) |

<Note>
  OpenCX retries on transient Zendesk failures but does not indefinitely retry past rate limits. Heavy backfills during peak hours can slow down. Run them overnight when possible.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Ticketing API" icon="envelope" href="/integrations/zendesk/ticketing-api">
    Re-verify email handoff credentials and webhook setup.
  </Card>

  <Card title="Sunshine Conversations" icon="messages" href="/integrations/zendesk/sunshine-conversations">
    Re-verify chat, SMS, WhatsApp, and social setup.
  </Card>

  <Card title="Channels" icon="grid-2" href="/integrations/zendesk/channels/widget">
    Per-channel implementation details for Widget, WhatsApp, SMS, Phone, and Email.
  </Card>

  <Card title="Handoff settings" icon="user-group" href="/handoff/introduction">
    Global handoff rules and office hours.
  </Card>
</CardGroup>


# Airtable
Source: https://docs.open.cx/knowledge/additional-sources/airtable/overview

Sync records from an Airtable base into the AI's training index so answers reference your structured product or support data.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync records from an Airtable base into the AI's training index so answers reference your structured product or support data.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# Asana
Source: https://docs.open.cx/knowledge/additional-sources/asana/overview

Sync project descriptions, task details, and team wikis from Asana into the AI's training index.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync project descriptions, task details, and team wikis from Asana into the AI's training index.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# BigQuery
Source: https://docs.open.cx/knowledge/additional-sources/bigquery/overview

Sync tables or views from BigQuery into the AI's training index so answers reference your data warehouse content.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync tables or views from BigQuery into the AI's training index so answers reference your data warehouse content.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# Coda
Source: https://docs.open.cx/knowledge/additional-sources/coda/overview

Sync Coda docs and tables into the AI's training index so answers draw on your team's internal runbooks and reference material.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync Coda docs and tables into the AI's training index so answers draw on your team's internal runbooks and reference material.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# CSV / Excel
Source: https://docs.open.cx/knowledge/additional-sources/csv-excel/overview

Upload CSV or Excel files for the AI to read as reference tables, FAQs, or structured product data.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Upload CSV or Excel files for the AI to read as reference tables, FAQs, or structured product data.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# GitHub
Source: https://docs.open.cx/knowledge/additional-sources/github/overview

Sync Markdown files, wiki pages, and READMEs from a GitHub repository into the AI's training index so answers reference your engineering docs.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync Markdown files, wiki pages, and READMEs from a GitHub repository into the AI's training index so answers reference your engineering docs.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# Google Docs
Source: https://docs.open.cx/knowledge/additional-sources/google-docs/overview

Sync individual Google Docs or an entire shared drive folder into the AI's training index so answers cite your internal documents.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync individual Google Docs or an entire shared drive folder into the AI's training index so answers cite your internal documents.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# Google Sheets
Source: https://docs.open.cx/knowledge/additional-sources/google-sheets/overview

Sync rows from Google Sheets into the AI's training index so answers can reference structured reference tables, FAQs, or product data.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync rows from Google Sheets into the AI's training index so answers can reference structured reference tables, FAQs, or product data.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# Monday.com
Source: https://docs.open.cx/knowledge/additional-sources/monday-com/overview

Sync board items and item updates from Monday.com into the AI's training index so answers reference your team's ongoing work.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync board items and item updates from Monday.com into the AI's training index so answers reference your team's ongoing work.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# MongoDB
Source: https://docs.open.cx/knowledge/additional-sources/mongodb/overview

Sync documents from a MongoDB collection into the AI's training index so answers reference your structured content store.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync documents from a MongoDB collection into the AI's training index so answers reference your structured content store.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# OneDrive
Source: https://docs.open.cx/knowledge/additional-sources/onedrive/overview

Sync files from a OneDrive folder into the AI's training index so answers reference your shared Word docs, PDFs, and spreadsheets.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync files from a OneDrive folder into the AI's training index so answers reference your shared Word docs, PDFs, and spreadsheets.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# REST API
Source: https://docs.open.cx/knowledge/additional-sources/rest-api/overview

Configure a REST endpoint that OpenCX polls for content to ingest — useful when your content lives in a custom internal system.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Configure a REST endpoint that OpenCX polls for content to ingest — useful when your content lives in a custom internal system.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# SharePoint
Source: https://docs.open.cx/knowledge/additional-sources/sharepoint/overview

Sync pages and documents from a SharePoint site into the AI's training index so answers draw on your intranet content.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync pages and documents from a SharePoint site into the AI's training index so answers draw on your intranet content.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# Slack
Source: https://docs.open.cx/knowledge/additional-sources/slack/overview

Sync pinned messages, canvases, or channel archives into the AI's training index so answers draw on institutional knowledge captured in Slack.

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync pinned messages, canvases, or channel archives into the AI's training index so answers draw on institutional knowledge captured in Slack.

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# Snowflake
Source: https://docs.open.cx/knowledge/additional-sources/snowflake/overview

Sync tables or views from Snowflake into the AI's training index so answers reference your data warehouse content (reference data, FAQs, SOPs).

<Note>
  This source isn't available as a one-click integration today. We track demand from customer requests — the more people ask, the sooner we prioritize it.
</Note>

## What this would do

Sync tables or views from Snowflake into the AI's training index so answers reference your data warehouse content (reference data, FAQs, SOPs).

## Today's alternatives

* **[Website crawler](/knowledge/sources/website/overview)** if the content is reachable at a public URL.
* **Direct training** via [AI Instructions](https://platform.open.cx/ai-instructions) for one-off content you paste or upload.

## Request it

Click **Request source** on the **Data Sources** page in the dashboard, or email support with the source name and what content you'd want synced. We route requests into the roadmap by demand.

***

## Related Documentation

<CardGroup>
  <Card title="Train via integrations" icon="brain" href="/knowledge/sources/overview">
    Sources you can connect today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Workaround for publicly reachable content.
  </Card>

  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Author content inside OpenCX.
  </Card>

  <Card title="Training overview" icon="book" href="/knowledge/introduction">
    Everything the agent reads from.
  </Card>
</CardGroup>


# Agent Knowledge
Source: https://docs.open.cx/knowledge/introduction

Three ways to teach your AI — write instructions directly, author a Help Center, or sync content from the tools you already use.

Your AI answers from what you put in front of it. OpenCX gives you three places to do that — pick the one closest to where the content already lives.

## The three ways OpenCX learns

<CardGroup>
  <Card title="AI Instructions" icon="sliders" href="/ai-instructions/overview">
    Write the agent's persona and answer rules directly — no source needed.
  </Card>

  <Card title="Help Center" icon="book-open" href="/help-center/overview">
    Author customer-facing articles that also ground the AI's replies.
  </Card>

  <Card title="Knowledge Sources" icon="brain" href="/knowledge/sources/overview">
    Sync Zendesk, Notion, Confluence, Shopify, your website, and more.
  </Card>
</CardGroup>

## Which should I pick?

Start from where your content already is. Duplicating content across surfaces creates drift — pick one home and add the others only when you have different content to put there.

* **AI Instructions** for rules the AI must always follow (tone, escalation triggers, policies) and for specific question-answer pairs you need exact control over. Fastest to ship; no connector required.
* **Help Center** if you want a customer-facing knowledge base *and* training material at the same time. Articles publish to your public Help Center and sync into the AI's training index.
* **Knowledge Sources** when the content lives in a tool your team already maintains — Zendesk, Notion, Confluence, Shopify, Intercom, Front, GitBook, Freshdesk, or any public website. Connect once; sync runs in the background.

<Tip>
  Not sure which source to connect? The decision table on [**Connect a knowledge source**](/knowledge/sources/overview) maps every source system to the right connector.
</Tip>

## What the AI actually reads

At answer time, the AI pulls from all three surfaces together. The AI Profile sets the voice; behavioral training scenarios enforce rules on every reply; scenario-specific training, Help Center articles, and synced sources are retrieved by relevance to the customer's question. Internal-only content (draft articles, segment-restricted content) surfaces only in agent-facing modes like Assist Mode — never in customer replies.

Publishing is explicit. Drafts in AI Instructions and the Help Center are never served to customers until you publish them. Syncs run in the background on each source's schedule.

***

## Related Documentation

<CardGroup>
  <Card title="AI Instructions" icon="sliders" href="/ai-instructions/overview">
    Profile, training scenarios, directories, version history.
  </Card>

  <Card title="Help Center" icon="book-open" href="/help-center/overview">
    Articles, topics, translations, validation.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    Pick the source, paste credentials, verify.
  </Card>

  <Card title="Autopilot topics" icon="compass" href="/handoff/topics">
    Gate which topics the AI answers vs. hands off.
  </Card>
</CardGroup>


# Connect Confluence
Source: https://docs.open.cx/knowledge/sources/confluence/connect

Paste your Atlassian domain, email, and API token — OpenCX pulls Confluence pages.

<Tip>
  Configure the source at [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
</Tip>

## Set up the sync

<Steps>
  <Step title="Open Data Sources">
    Go to [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
  </Step>

  <Step title="Add a Confluence source">
    Click **Add source → Confluence**.

    | Field | Example | Where to get it |
    | - | - | - |
    | **Domain** | `yourcompany.atlassian.net` | Your Atlassian instance domain. No `https://`. |
    | **Token type** | **API token** or **API token with scopes** | The kind of token you create for the field below. |
    | **Email** | `you@yourcompany.com` | The Atlassian account the API token belongs to. For a service account, its `@serviceaccount.atlassian.com` address. |
    | **API Token** | `ATATT…` | Generate at [Atlassian API tokens](https://id.atlassian.com/manage-profile/security/api-tokens). The token needs Confluence read access. For a token with scopes, see [Use an API token with scopes](#use-an-api-token-with-scopes). |
  </Step>

  <Step title="Start the sync">
    Click **Connect**. The first run does a full pull of every page the credentials can read. Large instances take longer — expect 10 minutes to an hour for thousands of pages.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Pages appear under **Confluence**, each linked to its source URL in your instance.
  </Step>
</Steps>

## Use an API token with scopes

A token with scopes can only read what you select, and a service account can own it, so the sync doesn't depend on a person's account.

<Steps>
  <Step title="Prepare the account">
    Use a service account or your own account. Give it access to Confluence and **View** permission on the spaces you want to sync.
  </Step>

  <Step title="Create the token">
    Create an API token with scopes for that account, choose **Confluence** as the app, and select every scope below. Scopes can't be added to a token later.

    | Scope | Lets OpenCX read |
    | - | - |
    | `read:page:confluence` | Pages and their content. Required today. |
    | `read:space:confluence` | Space names and keys. |
    | `read:attachment:confluence` | Files and images attached to pages. |
    | `read:label:confluence` | Labels. |
    | `read:hierarchical-content:confluence` | The page tree under a page. |
    | `read:content.metadata:confluence` | The pages above a page. |
    | `read:folder:confluence` | Folders that group pages. |

    All of them are read-only. Selecting them now means you won't need a new token if the sync starts reading more of your content.
  </Step>

  <Step title="Connect it">
    In the Confluence source, choose **API token with scopes**, then enter your site's `atlassian.net` domain, the account's email, and the token.
  </Step>
</Steps>

<Note>
  Scopes decide what kind of content the token can read. Space permissions decide which spaces sync: OpenCX only syncs the spaces the account can view.
</Note>

## What gets synced

<AccordionGroup>
  <Accordion title="All pages the credentials can read" icon="file-lines">
    Whole-instance pull. Page titles, body content (converted from Confluence storage format to HTML), and the `webui` back-link.
  </Accordion>

  <Accordion title="Visibility by space type" icon="eye">
    * Personal spaces (key starts with `~`) → **internal** — the AI uses them only in agent-facing surfaces.
    * All other spaces → **public** — the AI can cite them in customer replies.

    Override per-page in AI Instructions if a specific page needs different visibility.
  </Accordion>

  <Accordion title="Full refresh, not incremental" icon="arrows-rotate">
    Each sync run is a full re-pull with overwrite. The benefit: deletions in Confluence propagate correctly. The cost: each run is heavier than an incremental pull. Typical cadence is set by Airbyte's scheduler — adjust on the connection schedule if you need it less often for a huge instance.
  </Accordion>
</AccordionGroup>

## Limits

| | Value |
| - | - |
| **Streams synced** | `pages` |
| **Sync mode** | `full_refresh_overwrite` |
| **Sync cadence** | Airbyte polling — typically every few hours |
| **Credential type** | Domain + email + Atlassian API token, with or without scopes |
| **Deployment** | **Cloud only.** Server / Data Center not supported. |
| **Selective scoping** | None today — whole instance pulled |
| **Attachments** | Not synced |

***

## Related Documentation

<CardGroup>
  <Card title="Confluence overview" icon="confluence" href="/knowledge/sources/confluence/overview">
    What this source does and doesn't.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/confluence/troubleshooting">
    Auth errors, missing pages, slow syncs.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for scoped subsets.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Confluence
Source: https://docs.open.cx/knowledge/sources/confluence/overview

The Confluence source pulls pages from your Atlassian Cloud Confluence instance into the AI's training index.

<Note>
  Confluence is a **knowledge-only** source — OpenCX reads Confluence pages into the AI training index, but does not write back or operate Confluence. There is no companion control integration.
</Note>

The Confluence source pulls pages from your Atlassian Cloud Confluence instance into the AI's training index. Pages are converted from Confluence's <Tooltip>storage format</Tooltip> to HTML so the AI can retrieve them like any other article.

## What you get

* **Pages from all spaces the credentials can read.** Whole-instance sync today — no per-space picker.
* **Personal spaces are marked internal.** Any space whose key starts with `~` (Atlassian's personal-space convention) comes in as **internal**. Everything else is **public**.
* **Source URLs preserved.** Each synced page keeps its `webui` link back to Confluence so the AI can cite it.

## What's not supported today

* **Per-space scoping.** Whole-instance sync; use the [Website crawler](/knowledge/sources/website/overview) as a workaround if you only want a subset publicly reachable.
* **Attachments.** Only page body content is ingested.
* **Server / Data Center.** Cloud only.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Confluence" icon="plug" href="/knowledge/sources/confluence/connect">
    Domain, email, API token.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/confluence/troubleshooting">
    Auth errors, missing pages.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for scoped subsets.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Confluence troubleshooting
Source: https://docs.open.cx/knowledge/sources/confluence/troubleshooting

Start at the Confluence source row in Data Sources. Recent sync errors show there; for "sync completed but pages are missing", open AI Instructions and filter by Confluence.

Start at the **Confluence** source row in [**Data Sources**](https://platform.open.cx/data-sources). Recent sync errors show there; for "sync completed but pages are missing", open AI Instructions and filter by **Confluence**.

## Common scenarios

| Symptom | Likely cause | Fix |
| - | - | - |
| **Sync fails with 401 / unauthorized** | API token is invalid, revoked, or belongs to an account that doesn't have Confluence access | Re-generate the token at [Atlassian API tokens](https://id.atlassian.com/manage-profile/security/api-tokens). Confirm the email matches the token owner. Update both fields in the source. |
| **Sync fails with 401 or 404 after connecting an API token with scopes** | The token type in the source doesn't match the token, `read:page:confluence` is missing, or the account can't view the space | Edit the source and pick the token type that matches the token. Check the account has Confluence access and **View** on the space. Scopes can't be added to a token later, so create a new one with the [listed scopes](/knowledge/sources/confluence/connect#use-an-api-token-with-scopes) if any are missing. |
| **Connecting an API token with scopes asks for the atlassian.net address** | Tokens with scopes only work with your site's `atlassian.net` address, not a custom domain | Enter the domain as `yourcompany.atlassian.net`. |
| **"Space not accessible" errors in the logs** | The token's account doesn't have read permission for some spaces | Grant read access to the Confluence user in Atlassian space settings, or accept that restricted spaces are skipped. The rest of the sync proceeds. |
| **Pages from a personal space show as internal and the AI never cites them in customer replies** | Working as designed — personal spaces (keys starting with `~`) are marked internal | Override visibility per-page in [AI Instructions](https://platform.open.cx/ai-instructions), or move the content to a non-personal space in Confluence. |
| **Sync is extremely slow / times out on a huge instance** | `full_refresh_overwrite` pulls every page every run | Reduce the Confluence connection's sync cadence in the Airbyte schedule. If your instance has thousands of pages, consider breaking content out into a dedicated space and using the [Website crawler](/knowledge/sources/website/overview) against a public mirror. |
| **Source URLs in the AI's citations are missing or wrong** | The `webui` path is only assembled when the backend can look up your Confluence domain; if the domain didn't save, URLs are empty | Re-enter the **Domain** field exactly as `yourcompany.atlassian.net` (no scheme, no trailing slash). Trigger a re-sync. |
| **Confluence Server / Data Center** | Not supported today | Cloud only. Migrate or use the [Website crawler](/knowledge/sources/website/overview) against a published export. |
| **None of the above** | — | Contact support with the connection ID and sample page URL. |

***

## Related Documentation

<CardGroup>
  <Card title="Connect Confluence" icon="plug" href="/knowledge/sources/confluence/connect">
    Re-check credentials and limits.
  </Card>

  <Card title="Confluence overview" icon="confluence" href="/knowledge/sources/confluence/overview">
    What this source does.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for scoped subsets.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Connect Freshdesk
Source: https://docs.open.cx/knowledge/sources/freshdesk/connect

Paste your Freshdesk domain, API key, and rate limit — OpenCX pulls Solution articles.

<Tip>
  Configure the source at [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
</Tip>

## Set up the sync

<Steps>
  <Step title="Open Data Sources">
    Go to [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
  </Step>

  <Step title="Add a Freshdesk source">
    Click **Add source → Freshdesk**.

    | Field | Example | Where to get it |
    | - | - | - |
    | **Domain** | `yourcompany.freshdesk.com` | Your Freshdesk instance domain. |
    | **API Key** | `••••••••` | Profile settings → **View API Key** in Freshdesk. Needs Solutions read access. |
    | **Start date** | `2020-01-01T00:00:00Z` | Earliest article timestamp to include. Defaults to 2020-01-01 if left blank. |
    | **Requests per minute** | `50` (default) | Freshdesk's API rate limit per app per account. Lower this if you hit the cap while running other tools against the same API key. |
  </Step>

  <Step title="Start the sync">
    Click **Connect**. The first run pulls every Solution article — rate-limited to the value you set, so a large KB can take time.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Articles appear under **Freshdesk** with their HTML body and publish status reflected in visibility.
  </Step>
</Steps>

## Visibility rules

<AccordionGroup>
  <Accordion title="Status determines visibility" icon="eye">
    * `status === 2` (published) → **public** — AI cites in customer replies
    * `status === 1` (draft) → **internal** — agent-facing surfaces only
  </Accordion>
</AccordionGroup>

## Limits

| | Value |
| - | - |
| **Streams synced** | `solution_articles` |
| **Sync mode** | `full_refresh_overwrite` |
| **Sync cadence** | Airbyte polling — typically every few hours |
| **Credential type** | Domain + API key |
| **Rate limit** | Configurable 1–50 requests/min (default 50) |
| **Multi-account** | One Freshdesk account per connection |
| **Selective scoping** | None — whole Solutions section synced |

***

## Related Documentation

<CardGroup>
  <Card title="Freshdesk overview" icon="headset" href="/knowledge/sources/freshdesk/overview">
    What this source does.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/freshdesk/troubleshooting">
    Rate limits, folder visibility.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for scoped subsets.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Freshdesk
Source: https://docs.open.cx/knowledge/sources/freshdesk/overview

The Freshdesk source pulls Solution articles from your Freshdesk account into the AI's training index.

<Note>
  This page covers Freshdesk as a **knowledge source** — OpenCX reads Freshdesk Solution articles into the AI training index. To run the AI on your live Freshdesk tickets, see the separate [Freshdesk ticketing integration](/integrations/freshdesk/overview).
</Note>

The Freshdesk source pulls Solution articles from your Freshdesk account into the AI's training index. The AI can cite them in answers when customers ask questions your knowledge base already covers.

## What you get

* **Solution articles.** All articles in the `solution_articles` Freshdesk stream are synced — the hierarchy of categories and folders doesn't come through, but the article content does.
* **Visibility by status.** Published articles (status 2) are **public**; drafts (status 1) are **internal**.
* **HTML body preserved.** Article descriptions come through with their HTML formatting intact.

## What's not supported today

* **Per-category / per-folder scoping.** Whole Solutions section syncs.
* **Articles outside Solutions.** Ticket content, canned responses, and scenario automations aren't pulled.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Freshdesk" icon="plug" href="/knowledge/sources/freshdesk/connect">
    Domain, API key, rate limit.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/freshdesk/troubleshooting">
    Rate limits, folder visibility.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for scoped subsets.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Freshdesk troubleshooting
Source: https://docs.open.cx/knowledge/sources/freshdesk/troubleshooting

| Symptom | Likely cause | Fix | |---------|-------------|-----| | Sync fails with 429 / rate limit exceeded | Multiple tools are calling the same Freshdesk…

## Common scenarios

| Symptom | Likely cause | Fix |
| - | - | - |
| **Sync fails with 429 / rate limit exceeded** | Multiple tools are calling the same Freshdesk API key and pushing past the per-minute cap | Lower **Requests per minute** in the source (default 50, min 1). If the ceiling is still too low, request a rate-limit increase from Freshdesk. |
| **Some folders or categories are missing from the AI's answers** | The API key doesn't have read access to those folders — Freshdesk permissions are per-folder | Grant the API key's user access to the folders in Freshdesk, re-run the sync. The article hierarchy itself isn't preserved in OpenCX, but having the articles in the index is what matters. |
| **Drafts showing in public replies** | Happens only if an article's status got flipped in Freshdesk or the visibility was manually overridden in OpenCX | Confirm status in Freshdesk (should be 1 for drafts). Trigger a re-sync. Or override per-article in [AI Instructions](https://platform.open.cx/ai-instructions). |
| **First sync is very slow** | Rate limit × article count | Expected. Raise `requests_per_minute` if your Freshdesk plan allows, or let it finish overnight. Subsequent runs are much faster (they're incremental on article IDs). |
| **None of the above** | — | Contact support with the connection ID. |

***

## Related Documentation

<CardGroup>
  <Card title="Connect Freshdesk" icon="plug" href="/knowledge/sources/freshdesk/connect">
    Re-check credentials and rate limit.
  </Card>

  <Card title="Freshdesk overview" icon="headset" href="/knowledge/sources/freshdesk/overview">
    What this source does.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for scoped subsets.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Connect Front
Source: https://docs.open.cx/knowledge/sources/front/connect

| Field | Default | Notes | |-------|---------|-------| | Start date | One year ago | Earliest article activity to include.

<Tip>
  Configure the source at [**AI Training → Data Sources**](https://platform.open.cx/data-sources). This is separate from the [Front ticketing integration](/integrations/front/connect), though the same API token can power both.
</Tip>

## Set up the sync

<Steps>
  <Step title="Open Data Sources">
    Go to [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
  </Step>

  <Step title="Add a Front source">
    Click **Add source → Front**.

    | Field | Default | Notes |
    | - | - | - |
    | **Start date** | One year ago | Earliest article activity to include. Pick a date in `YYYY-MM-DDTHH:mm` format — the form provides a date picker. |
    | **API Key** | — | Front API token with **Knowledge Base: Read** scope. [Create one in the Front Developer Portal](https://dev.frontapp.com/docs/create-and-revoke-api-tokens). |
  </Step>

  <Step title="Select which Help Centers to sync">
    As soon as you paste a valid API key, OpenCX fetches the list of Help Centers on your Front account and shows them in a checkbox group with **type** (public / internal) and **locale** next to each name.

    * Leave all checked to sync every Help Center the token can read.
    * Uncheck internal Help Centers if you don't want their articles in the AI index.
    * Use **Select all** / **Deselect all** for quick toggling.

    <Warning>
      **Articles from unchecked Help Centers are filtered out at sync time** (`allowed_knowledge_base_ids` saved to your source config). If you later re-check a Help Center, articles from it start syncing on the next run.
    </Warning>
  </Step>

  <Step title="Start the sync">
    Click **Connect**. OpenCX saves your selection, creates the connection, and triggers the first sync. Progress shows on the source row.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Articles appear grouped under **Front**. Confirm the eye icon matches expectations — internal Help Centers come in as **internal**, public as **public** (if published).
  </Step>
</Steps>

## What gets synced

<AccordionGroup>
  <Accordion title="Published articles from selected Help Centers" icon="file-lines">
    Each article is fetched twice internally: once for metadata (via Airbyte), then once more via the Front API to pull full content. The final record has title, body, and source URL.
  </Accordion>

  <Accordion title="Visibility per Help Center + per article" icon="eye">
    Two layers combined:

    * **KB type:** If the Help Center's `type` in Front is `internal`, every article from it is **internal** in OpenCX.
    * **Article status:** Within a non-internal Help Center, only `published` articles are **public**. Drafts and archived articles are **internal**.
  </Accordion>

  <Accordion title="Incremental updates" icon="arrows-rotate">
    Sync runs on the Airbyte schedule (typically every few hours). Only articles whose `updated_at` changed since the last run are fetched. New articles in selected Help Centers are picked up automatically.
  </Accordion>
</AccordionGroup>

## Limits

| | Value |
| - | - |
| **Streams synced** | `knowledge_bases_articles` |
| **Sync mode** | `incremental_deduped_history` on `updated_at` |
| **Sync cadence** | Airbyte polling — typically every few hours |
| **Credential type** | Front API token (no OAuth) |
| **Multi-account** | One Front account per connection |
| **Selective scoping** | **Per-Help-Center via checkboxes.** Articles are not filterable at category or team level below Help Center. |
| **Archived / draft articles** | Synced as `internal` |

***

## Related Documentation

<CardGroup>
  <Card title="Front overview" icon="inbox" href="/knowledge/sources/front/overview">
    Scope and per-HC scoping summary.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/front/troubleshooting">
    KB list empty, private articles, re-sync.
  </Card>

  <Card title="Front integration" icon="inbox" href="/integrations/front/overview">
    Inbox, conversations, handoff.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Front
Source: https://docs.open.cx/knowledge/sources/front/overview

Sync Front Help Center articles into the AI training index, with per-Help-Center scoping.

<Note>
  This page covers **Front as a knowledge source** — syncing Help Center articles into the AI's training index. For **inbox connect, conversations, channels, and handoff**, see the [Front integration](/integrations/front/overview).
</Note>

The Front source pulls published articles from your Front Help Centers into the AI's training index. Unlike most sources, **Front lets you pick which Help Centers to sync** — useful when you have separate public, internal, and product-specific knowledge bases under one Front account.

## What's distinctive

* **Per-Help-Center scoping.** When you paste your API key, OpenCX fetches the list of Help Centers from your Front account and lets you check the boxes for the ones you want synced. Unchecked Help Centers are skipped entirely.
* **Visibility matches Front's own type.** Articles in Help Centers marked `internal` in Front come in as **internal** in OpenCX. Non-published articles (draft, archived) are also marked internal.
* **Article content is fetched per article.** The connector enriches each article with its full rendered content at sync time — not just metadata.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Front" icon="plug" href="/knowledge/sources/front/connect">
    API key, start date, Help Center selection.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/front/troubleshooting">
    KB list empty, private articles appearing.
  </Card>

  <Card title="Front integration" icon="inbox" href="/integrations/front/overview">
    Inbox, conversations, handoff.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    Compare sources.
  </Card>
</CardGroup>


# Front troubleshooting
Source: https://docs.open.cx/knowledge/sources/front/troubleshooting

Start at the Front source row in Data Sources. If you changed your Help Center selection recently, remember the new selection only applies to future syncs — existing indexed content from deselected…

Start at the **Front** source row in [**Data Sources**](https://platform.open.cx/data-sources). If you changed your Help Center selection recently, remember the new selection only applies to future syncs — existing indexed content from deselected Help Centers needs to be removed manually.

## Common scenarios

| Symptom | Likely cause | Fix |
| - | - | - |
| **Help Center picker shows "Failed to load Help Centers"** | The API key doesn't have **Knowledge Base: Read** scope, or is invalid | Re-generate the token in the [Front Developer Portal](https://dev.frontapp.com/docs/create-and-revoke-api-tokens) with the right scope. Paste it — the picker auto-retries. |
| **An internal Front article is showing in customer-facing replies** | Either the Help Center's type in Front isn't set to `internal`, or the article was once in a public HC and got moved | Confirm the Help Center `type` in Front. If it's `internal`, trigger a re-sync — OpenCX will flip the visibility. If it's public but this specific article shouldn't be, override visibility per-article in [AI Instructions](https://platform.open.cx/ai-instructions) via the eye icon. |
| **I deselected a Help Center but its articles still appear** | Deselection filters future syncs; existing items stay indexed until removed | Open AI Instructions, filter by **Front** source and the Help Center name, bulk-delete. Future syncs won't re-fetch those articles. |
| **The picker's checkboxes resolve to a different count than I saved** | The connection picks up any new Help Centers you've added in Front since the last save, and applies the previously saved `allowed_knowledge_base_ids` filter to unchanged ones | Open the source, review the list, update selections, save. The picker shows all currently-accessible Help Centers from the token. |
| **Drafts from Front appear in the AI's answers** | Draft articles sync as `internal` but can still surface in agent-facing tools | If that's unwanted, publish the article in Front (moves it to `public`) or override visibility in AI Instructions. |
| **None of the above** | — | Contact support with the connection ID and the HC names you expected vs. see. |

## Limits

| | Value |
| - | - |
| **Selective scoping** | Per-Help-Center checkboxes; no sub-category scoping |
| **Multi-account** | Not supported today |
| **Sync cadence** | Airbyte polling — typically every few hours |
| **Deselection behavior** | Filters future syncs only; existing items must be manually deleted |

***

## Related Documentation

<CardGroup>
  <Card title="Connect Front" icon="plug" href="/knowledge/sources/front/connect">
    Re-check credentials and Help Center picker.
  </Card>

  <Card title="Front overview" icon="inbox" href="/knowledge/sources/front/overview">
    What this source does.
  </Card>

  <Card title="Front integration" icon="inbox" href="/integrations/front/overview">
    Inbox, handoff, conversations.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Connect GitBook
Source: https://docs.open.cx/knowledge/sources/gitbook/connect

| Field | Example | Where to get it | |-------|---------|-----------------| | Space ID | abc123xyz | Open the space in GitBook — the ID is in the URL after /space/ or findable via the GitBook API.

<Tip>
  Configure the source at [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
</Tip>

## Set up the sync

<Steps>
  <Step title="Open Data Sources">
    Go to [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
  </Step>

  <Step title="Add a GitBook source">
    Click **Add source → GitBook**.

    | Field | Example | Where to get it |
    | - | - | - |
    | **Space ID** | `abc123xyz` | Open the space in GitBook — the ID is in the URL after `/space/` or findable via the GitBook API. |
    | **Access Token** | `gb_…` | [Create a personal access token](https://developer.gitbook.com/gitbook-api/authentication) in your GitBook account. It must have read access to the space. |
  </Step>

  <Step title="Start the sync">
    Click **Connect**. The first run pulls all pages in the space, typically in seconds to a minute.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Content appears under **GitBook**, linked to the page URLs in your GitBook space.
  </Step>
</Steps>

## What gets synced

<AccordionGroup>
  <Accordion title="Content pages" icon="file-lines">
    Every page in the space, with title and body. Nested pages flattened into the index but keep their GitBook URL.
  </Accordion>

  <Accordion title="Workspace metadata" icon="users">
    Users, organizations, insights, and org members sync as context. The AI uses these sparingly — they're not the main driver for answers.
  </Accordion>

  <Accordion title="Visibility" icon="eye">
    * Published content → **public**
    * Unpublished content → **internal**

    Toggle visibility in GitBook; it flips on the next sync.
  </Accordion>
</AccordionGroup>

## Limits

| | Value |
| - | - |
| **Streams synced** | `content`, `users`, `organizations`, `insights`, `org_members` |
| **Sync mode** | `full_refresh_append` |
| **Sync cadence** | Airbyte polling — typically every few hours |
| **Credential type** | Personal access token |
| **Multi-space** | One space per connection (add more connections for more spaces) |
| **Selective scoping** | None — hide pages in GitBook to keep them out |

***

## Related Documentation

<CardGroup>
  <Card title="GitBook overview" icon="book" href="/knowledge/sources/gitbook/overview">
    Scope and behavior.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/gitbook/troubleshooting">
    Auth, wrong space, empty content.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for public GitBook sites.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# GitBook
Source: https://docs.open.cx/knowledge/sources/gitbook/overview

The GitBook source syncs the content stream (plus workspace metadata like users, organizations, and org members for context) from one GitBook space.

<Note>
  GitBook is a **knowledge-only** source — OpenCX reads GitBook content into the AI training index.
</Note>

The GitBook source syncs the `content` stream (plus workspace metadata like users, organizations, and org members for context) from one GitBook space. Use this when your product docs, help articles, or internal runbooks are authored in GitBook.

## What you get

* **Content from one space** — pages, nested pages, and their body content.
* **Source URLs preserved** — the `website` or `content` URL of each page, so the AI cites accurately.
* **Visibility by publish state** — published content is **public**, unpublished content is **internal**.

## Scope

* **One space per connection** — add a second source if you sync multiple spaces.
* **All pages in the space** — no per-page scoping. Hide pages inside GitBook if you don't want them indexed.

***

## Related Documentation

<CardGroup>
  <Card title="Connect GitBook" icon="plug" href="/knowledge/sources/gitbook/connect">
    Access token, space ID.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/gitbook/troubleshooting">
    Auth, wrong space, empty content.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for public GitBook sites.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Gitbook troubleshooting
Source: https://docs.open.cx/knowledge/sources/gitbook/troubleshooting

| Symptom | Likely cause | Fix | |---------|-------------|-----| | Sync fails with unauthorized | Access token is invalid, expired, or lacks read access to…

## Common scenarios

| Symptom | Likely cause | Fix |
| - | - | - |
| **Sync fails with unauthorized** | Access token is invalid, expired, or lacks read access to the specified space | [Regenerate the token](https://developer.gitbook.com/gitbook-api/authentication) with the right scope and update the source. |
| **Space ID not found** | The **Space ID** field is wrong or you entered a collection ID instead | Open the space in GitBook, pull the ID from the URL (after `/space/`) or from the GitBook API. Update the source. |
| **Sync succeeds but the content folder is empty** | The token can authenticate but doesn't have read access to the content stream of that space | Verify the token's access in GitBook. Some tokens are scoped to specific content — use one with full space read. |
| **I want a second space synced** | One space per connection | Add a second GitBook source in OpenCX with a different space ID (and optionally a different token). |
| **None of the above** | — | Contact support with the connection ID. |

***

## Related Documentation

<CardGroup>
  <Card title="Connect GitBook" icon="plug" href="/knowledge/sources/gitbook/connect">
    Re-check credentials and space ID.
  </Card>

  <Card title="GitBook overview" icon="book" href="/knowledge/sources/gitbook/overview">
    What this source does.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for public GitBook sites.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Connect HubSpot Knowledge Base
Source: https://docs.open.cx/knowledge/sources/hubspot-kb/connect

Create a HubSpot Private App access token, paste it into Data Sources, and OpenCX pulls your published Knowledge Base articles.

<Tip>
  Configure the source at [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
</Tip>

<Warning>
  Only **published** Knowledge Base articles are synced. HubSpot indexes drafts separately and does not expose them to third-party integrations. Publish articles in HubSpot before expecting them in OpenCX.
</Warning>

## Set up the sync

<Steps>
  <Step title="Create a HubSpot Private App">
    In HubSpot, go to **Settings → Integrations → Private Apps** and create an app. Add the `cms.knowledge_base.articles.read` scope so OpenCX can read full Knowledge Base article bodies through HubSpot GraphQL. See [HubSpot's private apps guide](https://developers.hubspot.com/docs/guides/apps/private-apps/overview).
  </Step>

  <Step title="Open Data Sources">
    Go to [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
  </Step>

  <Step title="Add a HubSpot Knowledge Base source">
    Click **Add source → HubSpot Knowledge Base**.

    | Field | Example | Where to get it |
    | - | - | - |
    | **Private App Access Token** | `pat-na1-…` or `pat-eu1-…` | The scoped access token from the private app you created above. |
  </Step>

  <Step title="Start the sync">
    Click **Connect**. OpenCX validates HubSpot Knowledge Base GraphQL access, auto-detects your portal ID, and starts a full pull of **published** articles with their full body content. Large knowledge bases take longer.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Published articles appear under **HubSpot Knowledge Base**, each linked to its source URL in your help center.
  </Step>
</Steps>

## What gets synced

<AccordionGroup>
  <Accordion title="Published articles only" icon="file-lines">
    Whole-account pull of articles HubSpot exposes through Knowledge Base GraphQL. Titles, full article bodies, source URLs, and selected HubSpot metadata are stored for retrieval.
  </Accordion>

  <Accordion title="Visibility" icon="eye">
    Published articles with public HubSpot access rules are stored as **public** knowledge. Published articles with restricted HubSpot access rules are stored as **internal** knowledge. Drafts and unpublished articles are **not** pulled and never appear in the index.
  </Accordion>

  <Accordion title="Full refresh, not incremental" icon="arrows-rotate">
    Each sync run is a full re-pull with overwrite, so unpublishing or deleting an article in HubSpot removes it from the index on the next successful sync. The cost is that each run is heavier than an incremental pull — adjust the cadence on the connection schedule if you have a very large knowledge base.
  </Accordion>
</AccordionGroup>

## Limits

| | Value |
| - | - |
| **Streams synced** | `articles` |
| **Sync mode** | `full_refresh_overwrite` |
| **Sync cadence** | Airbyte polling — typically every few hours |
| **Credential type** | HubSpot Private App access token with `cms.knowledge_base.articles.read` |
| **API used** | HubSpot GraphQL Knowledge Base (`KB.knowledge_article_collection`) |
| **Draft handling** | **Not synced** — publish in HubSpot first |
| **Multi-account** | One HubSpot portal per source |
| **Selective scoping** | None today — whole published index pulled |

***

## Related Documentation

<CardGroup>
  <Card title="HubSpot Knowledge Base overview" icon="hubspot" href="/knowledge/sources/hubspot-kb/overview">
    What this source does and doesn't.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/hubspot-kb/troubleshooting">
    Auth errors, missing articles, slow syncs.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for draft HTML or scoped subsets.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# HubSpot Knowledge Base
Source: https://docs.open.cx/knowledge/sources/hubspot-kb/overview

The HubSpot Knowledge Base source pulls your published help articles into the AI's training index so answers cite your existing HubSpot content.

<Note>
  This page covers **HubSpot as a knowledge source** — syncing Knowledge Base articles into the AI's training index. For **operating HubSpot** (tickets, handoff, conversations, CRM context), see the [HubSpot integration](/integrations/hubspot/overview).
</Note>

The HubSpot Knowledge Base source pulls **published** articles from your HubSpot <Tooltip>Knowledge Base</Tooltip> into the AI's training index. OpenCX uses HubSpot **GraphQL Knowledge Base** access so synced articles include their full body content and source metadata.

## What you get

* **Published articles with full body content.** Whole-account sync today — no per-knowledge-base or per-category picker.
* **Drafts are not synced.** Only articles HubSpot reports as published are pulled. Draft, scheduled, and unpublished articles stay in HubSpot only.
* **Source URLs preserved.** Each synced article keeps its public HubSpot help-center URL so the AI can link back to it.
* **HubSpot metadata preserved.** Language, summary, publish/update timestamps, category ID, and access rule metadata are stored with the article.

## What's not supported today

* **Draft or unpublished articles.** Publish an article in HubSpot first, or use another source (manual upload, website crawler) for draft content.
* **Per-knowledge-base or per-category scoping.** The whole portal's published Knowledge Base collection is pulled. Use the [Website crawler](/knowledge/sources/website/overview) as a workaround if you only want a publicly reachable subset.
* **HubSpot accounts without Knowledge Base GraphQL.** The source requires HubSpot's latest Knowledge Base GraphQL support and a token with `cms.knowledge_base.articles.read`.

***

## Related Documentation

<CardGroup>
  <Card title="Connect HubSpot Knowledge Base" icon="plug" href="/knowledge/sources/hubspot-kb/connect">
    Private App access token.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/hubspot-kb/troubleshooting">
    Auth errors, missing articles.
  </Card>

  <Card title="HubSpot integration" icon="hubspot" href="/integrations/hubspot/overview">
    Tickets, handoff, CRM context.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# HubSpot Knowledge Base troubleshooting
Source: https://docs.open.cx/knowledge/sources/hubspot-kb/troubleshooting

Start at the HubSpot Knowledge Base source row in Data Sources. Recent sync errors show there; for "sync completed but articles are missing", open AI Instructions and filter by HubSpot Knowledge Base.

Start at the **HubSpot Knowledge Base** source row in [**Data Sources**](https://platform.open.cx/data-sources). Recent sync errors show there; for "sync completed but articles are missing", open AI Instructions and filter by **HubSpot Knowledge Base**.

## Common scenarios

| Symptom | Likely cause | Fix |
| - | - | - |
| **Sync fails at connect with portal ID error** | The access token is invalid, expired, or from a different HubSpot account | Create a fresh **Private App** access token for the correct portal and update the source. |
| **Sync fails with a GraphQL or auth error** | The token is missing `cms.knowledge_base.articles.read`, the private app was not reinstalled after adding the scope, or the account does not expose Knowledge Base GraphQL | Add the scope, reinstall/save the private app, confirm `KB` appears in HubSpot GraphiQL for the portal, then update the source. |
| **Sync completes but zero articles** | All Knowledge Base articles are still **drafts** or unpublished | Publish articles in HubSpot, then run the sync again. |
| **Some published articles are missing** | The articles are not returned by HubSpot Knowledge Base GraphQL for this portal or they are not in the latest Knowledge Base toolset | Confirm the articles appear in HubSpot GraphiQL under `KB.knowledge_article_collection`, or contact HubSpot support to enable KB GraphQL for the account. |
| **Draft articles never appear** | Working as designed — this source only imports published articles | Publish in HubSpot, or ingest draft content via file upload / website crawler. |
| **Article body is empty** | HubSpot returned an empty `hs_body` for that article | Check the article in HubSpot GraphiQL. If `hs_body` is empty there too, update the article content in HubSpot. |
| **Sync is slow / times out on a large knowledge base** | `full_refresh_overwrite` re-queries the full Knowledge Base GraphQL collection each run | Reduce the connection's sync cadence on the Airbyte schedule. |
| **None of the above** | — | Contact support with the connection ID and a sample article URL. |

***

## Related Documentation

<CardGroup>
  <Card title="Connect HubSpot Knowledge Base" icon="plug" href="/knowledge/sources/hubspot-kb/connect">
    Re-check the token and limits.
  </Card>

  <Card title="HubSpot Knowledge Base overview" icon="hubspot" href="/knowledge/sources/hubspot-kb/overview">
    What this source does.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for full HTML or scoped subsets.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Connect Intercom
Source: https://docs.open.cx/knowledge/sources/intercom/connect

Connect Intercom as a knowledge source with an access token to sync Help Center articles and content snippets. Covers setup, sync cadence, and limits.

<Tip>
  Configure the source at [**AI Training → Data Sources**](https://platform.open.cx/data-sources). Not the same place as the [ticketing integration](/integrations/intercom/connect) — this is knowledge only.
</Tip>

## Set up the sync

<Steps>
  <Step title="Open Data Sources">
    Go to [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
  </Step>

  <Step title="Add an Intercom source">
    Click **Add source → Intercom**.

    | Field | Example | Where to get it |
    | - | - | - |
    | **Access token** | `dG9rOjVj…` | Intercom Developer Hub → your app → **Access Token**. Needs read access to articles and content snippets. Can be the same token as the ticketing integration. |
    | **Start date** | `2024-01-01T00:00:00Z` | The form asks for one, but it doesn't limit the sync: every published article and content snippet is synced. |
  </Step>

  <Step title="Start the sync">
    Click **Connect**. The first sync imports every published article and content snippet, usually within a few minutes.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Items appear under **Intercom → Articles** and **Intercom → Content Snippets**. If the folders are empty, see [Troubleshooting](/knowledge/sources/intercom/troubleshooting).
  </Step>
</Steps>

## Limits

| | Value |
| - | - |
| **Content synced** | Published Help Center articles and content snippets |
| **Languages** | Each article's default language; translations aren't synced |
| **Sync cadence** | Daily, and right after you connect or save the source |
| **Removals** | Unpublished or deleted articles and deleted snippets are removed on the next sync |
| **Credential type** | Personal access token (no OAuth in this surface) |
| **Conversations** | Not synced |
| **Multi-workspace** | One Intercom workspace per connection |
| **Selective scoping** | None — every published article and content snippet the token can read is synced |

***

## Related Documentation

<CardGroup>
  <Card title="Intercom overview" icon="intercom" href="/knowledge/sources/intercom/overview">
    What this source does and what it doesn't.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/intercom/troubleshooting">
    Sync silently empty, auth failures.
  </Card>

  <Card title="Intercom integration" icon="intercom" href="/integrations/intercom/overview">
    Inbox, conversations, handoff.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    Compare sources.
  </Card>
</CardGroup>


# Intercom
Source: https://docs.open.cx/knowledge/sources/intercom/overview

Sync published Intercom Help Center articles and content snippets into the AI's training index. Read this to see what syncs, what stays internal, and what doesn't.

<Note>
  This page covers **Intercom as a knowledge source** — syncing your Help Center articles and content snippets so the AI can answer from them. For **inbox connect, conversations, and handoff**, see the [Intercom integration](/integrations/intercom/overview).
</Note>

The Intercom source syncs your published Help Center articles and your <Tooltip>content snippets</Tooltip> into the AI's training index, so the AI answers from the same content your customers and your Intercom AI agent already rely on.

## What syncs

* **Published Help Center articles**, in each article's default language. Every item links back to the article's public page. Drafts aren't synced.
* **Content snippets.** Snippets available to Intercom's AI agent are used in customer replies. Snippets limited to your team or to specific audiences are imported as internal and aren't used in customer replies.
* **Removals.** Articles you unpublish or delete, and snippets you delete, are removed on the next sync.

Not synced: article translations, conversations, and guidance rules from Intercom's AI agent. Add guidance as [AI Instructions](/ai-instructions/overview).

## Credentials

One access token with read access to articles and content snippets. The same Personal Access Token you use for the [ticketing integration](/integrations/intercom/connect) works.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Intercom" icon="plug" href="/knowledge/sources/intercom/connect">
    Access token, first sync, limits.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/intercom/troubleshooting">
    Sync silently empty, segments instead of articles.
  </Card>

  <Card title="Intercom integration" icon="intercom" href="/integrations/intercom/overview">
    Inbox, conversations, handoff.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    Compare sources.
  </Card>
</CardGroup>


# Intercom troubleshooting
Source: https://docs.open.cx/knowledge/sources/intercom/troubleshooting

Start at the Intercom source row in Data Sources. If the latest sync errored, the message appears there. For "sync succeeded but I don't see anything", work through the scenarios below.

Start at the **Intercom** source row in [**Data Sources**](https://platform.open.cx/data-sources). If the latest sync errored, the message appears there. For "sync succeeded but I don't see anything", work through the scenarios below.

## Common scenarios

| Symptom | Likely cause | Fix |
| - | - | - |
| **Sync says "succeeded" but nothing appears in AI Instructions** | The workspace has no published articles or content snippets, or the token can't read them | Check that the articles are published in Intercom. Re-generate the access token with read access to articles and content snippets and update the source. If content exists and the token can read it, contact support with the connection ID. |
| **I see Intercom segments instead of articles** | The source was connected before article sync was available and still syncs segments | Disconnect the Intercom source in Data Sources and connect it again. The first sync imports your articles and content snippets and removes the segment items. |
| **A content snippet isn't used in customer replies** | In Intercom, the snippet is limited to your team or to specific audiences, so it's imported as internal | Make the snippet available to Intercom's AI agent for all customers. The change applies on the next sync. |
| **An article I unpublished still appears** | Removals apply on the next sync | Wait for the daily sync, or save the source in Data Sources to sync now. |
| **Connection errored with "unauthorized"** | Access token is wrong, revoked, or for a different Intercom workspace | Re-paste the token. Confirm the workspace matches. The token shown as `**********` in the dashboard is redacted — you must re-type the real value to verify it. |
| **Multi-workspace org — only one workspace syncs** | One connection = one workspace today | Add a second OpenCX organization for the second workspace, or escalate to support. |
| **None of the above** | — | Contact support with the connection ID. |

***

## Related Documentation

<CardGroup>
  <Card title="Connect Intercom" icon="plug" href="/knowledge/sources/intercom/connect">
    Re-check credentials and limits.
  </Card>

  <Card title="Intercom overview" icon="intercom" href="/knowledge/sources/intercom/overview">
    What this source does today.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for Intercom Help Center articles.
  </Card>

  <Card title="Intercom integration" icon="intercom" href="/integrations/intercom/overview">
    Inbox, conversations, handoff.
  </Card>
</CardGroup>


# Connect Notion
Source: https://docs.open.cx/knowledge/sources/notion/connect

Approve. You're redirected back to the OpenCX dashboard with the connection active.

<Tip>
  Configure the source at [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
</Tip>

## Set up the sync

<Steps>
  <Step title="Open Data Sources">
    Go to [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
  </Step>

  <Step title="Start the Notion connection">
    Click **Add source → Notion**. There are no credential fields — Notion uses OAuth.
  </Step>

  <Step title="Authorize in Notion">
    Click **Connect**. A Notion authorization page opens. **This is where you choose what OpenCX can read:**

    * **Allow access to all pages** — broadest. The connector can see every page in the workspace it's installed in.
    * **Select pages** — narrow. Pick specific pages or databases. OpenCX only sees those.

    Approve. You're redirected back to the OpenCX dashboard with the connection active.
  </Step>

  <Step title="Wait for the first sync">
    The first pull indexes every accessible page and its content. Size depends on how much you shared — small workspaces finish in minutes, larger ones take longer.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Each page appears under **Notion** as one article, titled after the page and linked back to its page URL.
  </Step>
</Steps>

## What gets synced

<AccordionGroup>
  <Accordion title="Pages" icon="file-lines">
    Every Notion page the OAuth scope grants access to — both top-level pages and sub-pages.
  </Accordion>

  <Accordion title="Page content" icon="cubes">
    Headings, paragraphs, lists, to-dos, quotes, callouts, code and tables inside each page, including nested blocks, are assembled into that page's article in reading order. Edits to a page's content show up on the next incremental run. Images and files contribute their captions only.
  </Accordion>

  <Accordion title="Databases as pages" icon="table">
    Database rows in Notion are treated as pages at sync time. The AI sees each row's content but doesn't query the database structurally.
  </Accordion>
</AccordionGroup>

## Changing scope later

To expand or narrow what the connector sees:

1. Remove the connection from Data Sources in OpenCX.
2. In Notion, visit **Settings → Connections** and revoke the OpenCX integration (or leave it and skip this step if you'll re-authorize).
3. Re-add the source in OpenCX and re-authorize — this time picking a different set of pages.

## Limits

| | Value |
| - | - |
| **Streams synced** | `pages`, `blocks` |
| **Sync mode** | `incremental_deduped_history` on `last_edited_time` |
| **Sync cadence** | Airbyte polling — typically every few hours |
| **Credential type** | OAuth 2.0 (no API token) |
| **Multi-workspace** | One Notion workspace per connection |
| **Selective scoping** | Set at OAuth authorization time — change by revoke + re-connect |

***

## Related Documentation

<CardGroup>
  <Card title="Notion overview" icon="n" href="/knowledge/sources/notion/overview">
    What this source does.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/notion/troubleshooting">
    Missing pages, re-authorization.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    For publicly-shared Notion pages.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Notion
Source: https://docs.open.cx/knowledge/sources/notion/overview

The Notion source syncs the pages and blocks you grant access to in your Notion workspace.

<Note>
  Notion is a **knowledge-only** source — OpenCX reads Notion content into the AI training index but does not operate Notion as a control surface.
</Note>

The Notion source syncs the pages you grant access to in your Notion workspace, one article per page. Connection is OAuth-based — you pick which pages or databases the integration can see during authorization, and OpenCX ingests everything within that scope.

## How it works

* **OAuth 2.0.** No API token to paste. You authorize the connection in Notion, pick what to share, and OpenCX inherits that scope.
* **One article per page.** Each page becomes a single article, titled after the page, with its full content (including nested blocks) in reading order. Both `pages` and `blocks` streams sync on `last_edited_time`. Incremental — edits in Notion show up on the next run.
* **Scope matches what you shared.** Notion's integration model puts you in control of what the OpenCX connector can read. Narrow the scope inside Notion if you want to limit it.

## What's not supported today

* **Per-page filtering after authorization.** Scope is set in Notion at authorization time — change it by revoking and re-authorizing with a different selection.
* **Databases as structured data.** Notion databases are synced as pages (the row content), not as queryable tables.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Notion" icon="plug" href="/knowledge/sources/notion/connect">
    OAuth flow and scope.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/notion/troubleshooting">
    Pages missing, scope changes.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>

  <Card title="Training scenarios" icon="rabbit" href="/ai-instructions/training-scenarios">
    Q\&A pairs for content the connector can't see.
  </Card>
</CardGroup>


# Notion troubleshooting
Source: https://docs.open.cx/knowledge/sources/notion/troubleshooting

Notion scope is set at OAuth authorization time, not at the OpenCX source. Most "missing content" issues trace back to the Notion integration's selected pages, not to OpenCX.

Notion scope is set at OAuth authorization time, not at the OpenCX source. Most "missing content" issues trace back to the Notion integration's selected pages, not to OpenCX.

## Common scenarios

| Symptom | Likely cause | Fix |
| - | - | - |
| **Expected pages aren't in AI Instructions** | During OAuth, you picked **Select pages** and didn't include them | Remove the connection in OpenCX, re-authorize with broader scope, then re-sync. Or, in Notion's own **Settings → Connections**, edit which pages OpenCX can access — the next sync picks up the change. |
| **I shared access to a page but its sub-pages are missing** | Notion's permission model doesn't cascade shared access to every sub-page automatically; each needs explicit sharing or the parent must grant recursive access | In Notion, open the parent page → **Connections** → ensure the OpenCX integration is added. Sub-pages inherit if the parent grants. |
| **Private pages are appearing** | Notion's OAuth is based on what you shared at authorization. If "Allow all" was picked, all private pages under that workspace are in scope. | Revoke the OpenCX integration in Notion's **Settings → Connections**, re-authorize from OpenCX with a narrower selection. |
| **Page edits take hours to show up** | Incremental sync on `last_edited_time` — Airbyte's schedule determines the lag | Trigger an immediate sync from the source row in Data Sources. For structural edits (new pages, reorganizations), a full run is triggered next cycle. |
| **Database rows are synced but I can't query them as a table** | By design — the connector syncs rows as pages for retrieval, not as a queryable table | Re-model the database as pages, or use [AI Actions](/actions/introduction) on the Notion API if you need query behavior. |
| **None of the above** | — | Contact support with the connection ID and a sample Notion page URL. |

***

## Related Documentation

<CardGroup>
  <Card title="Connect Notion" icon="plug" href="/knowledge/sources/notion/connect">
    Re-authorize with different scope.
  </Card>

  <Card title="Notion overview" icon="n" href="/knowledge/sources/notion/overview">
    What this source does.
  </Card>

  <Card title="Training scenarios" icon="rabbit" href="/ai-instructions/training-scenarios">
    Add content the connector can't see.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources.
  </Card>
</CardGroup>


# Connect a knowledge source
Source: https://docs.open.cx/knowledge/sources/overview

Pick the source system where your content already lives and connect it — OpenCX keeps your AI in sync on a schedule.

<Note>
  This page covers **ingestion** — getting your content into the AI's training index so it can ground answers. If you want the AI to **operate** a third-party platform (route tickets, send messages, run AI Actions), those capabilities live under [Integrations](/dashboard/introduction). Vendors that appear in both — **Zendesk**, **Shopify**, **Intercom**, **Front** — link across from each overview page.
</Note>

Knowledge sources land in the AI's vector index. The agent retrieves from them at answer time and cites them in replies. Connect once; the content stays in sync.

<Tip>
  Configure sources at [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
</Tip>

## Connect today

Match the source system first — don't duplicate content just to suit the connector.

| If your content lives in… | Use |
| - | - |
| A **public help center or website** | [Website crawler](/knowledge/sources/website/overview) |
| A **Zendesk Help Center** | [Zendesk](/knowledge/sources/zendesk/overview) |
| An **Intercom Help Center** or Intercom content snippets | [Intercom](/knowledge/sources/intercom/overview) |
| A **Front Help Center** | [Front](/knowledge/sources/front/overview) |
| **Confluence** spaces | [Confluence](/knowledge/sources/confluence/overview) |
| A **Notion** workspace | [Notion](/knowledge/sources/notion/overview) |
| A **Shopify** store (pages, blog, products) | [Shopify](/knowledge/sources/shopify/overview) |
| **GitBook** documentation | [GitBook](/knowledge/sources/gitbook/overview) |
| **Freshdesk** Solution articles | [Freshdesk](/knowledge/sources/freshdesk/overview) |
| You want to **author directly inside OpenCX** | [Help Center](/help-center/overview) |
| You need a **specific Q\&A** or a **rule** | [AI Instructions](/ai-instructions/overview) |

Not on the list? Browse [Additional sources](/knowledge/additional-sources/google-docs/overview) — every entry has a **Request** button that goes straight to our roadmap queue.

<Warning>
  Don't double up on the same content. If you sync a Zendesk Help Center through the Zendesk source, don't also run the website crawler against `help.yourcompany.com` — you'll index every article twice and the AI will surface duplicates.
</Warning>

## How a source gets connected

<Steps>
  <Step title="Open Data Sources">
    Sign in to your [OpenCX dashboard](https://platform.open.cx/data-sources) and go to **AI Training → Data Sources**.
  </Step>

  <Step title="Pick the source">
    Click **Add source** and select the connector. Each source has its own credential fields — the **Connect** page for each vendor mirrors the dashboard form label-for-label.
  </Step>

  <Step title="Wait for the first sync">
    The first run pulls everything historical. It takes minutes to hours depending on volume. Progress shows on the source row.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Synced content appears grouped by source. Check a known article — it should show with the source name and the expected visibility (eye icon).
  </Step>
</Steps>

## What to expect after connecting

| | Value |
| - | - |
| **Sync cadence** | Most sources poll every few hours. The website crawler runs on an interval you set (default and minimum 7 days). Trigger a manual sync from the source row anytime. |
| **Visibility derivation** | Every item is tagged **public** or **internal** from the source system's own signals (drafts, user segments, space type, publish status). Rules per source are on each **Connect** page. |
| **Index scope** | One knowledge index per OpenCX org. Separate knowledge pools mean separate orgs — flag it with support if you're hitting this. |
| **Deletion** | Removing a source deletes the synced items from the index. The content in the source system is untouched. Re-adding re-pulls everything. |

***

## Related Documentation

<CardGroup>
  <Card title="AI Instructions" icon="sliders" href="/ai-instructions/overview">
    Rules, Q\&A pairs, and AI persona edited directly in OpenCX.
  </Card>

  <Card title="Help Center" icon="book-open" href="/help-center/overview">
    Author customer-facing articles that also train the AI.
  </Card>

  <Card title="Additional sources" icon="layer-group" href="/knowledge/additional-sources/google-docs/overview">
    Don't see your tool? Browse and request it.
  </Card>

  <Card title="Agent Knowledge overview" icon="book" href="/knowledge/introduction">
    The three ways OpenCX learns.
  </Card>
</CardGroup>


# Connect Shopify
Source: https://docs.open.cx/knowledge/sources/shopify/connect

Create a Shopify custom app, authorize via OAuth, and pick which streams to sync.

<Tip>
  Configure the source at [**AI Training → Data Sources**](https://platform.open.cx/data-sources). This is separate from the [Shopify store connection](/integrations/shopify/connect) used for AI Actions and metadata enrichment — the two can share a custom app if the scopes overlap.
</Tip>

## Before you start

<AccordionGroup>
  <Accordion title="A Shopify custom app with the right scopes" icon="circle-check">
    Knowledge sync authorizes via OAuth using a custom app's **Client ID** and **Client Secret**. Required scopes per stream:

    | Stream | Required scope |
    | - | - |
    | Pages | `read_online_store_pages` |
    | Articles | `read_content` |
    | Products | `read_products` |

    If the custom app you use for the [store connection](/integrations/shopify/connect) already has these scopes, reuse it. Otherwise add them, or create a second custom app just for knowledge sync.
  </Accordion>

  <Accordion title="Owner or admin in OpenCX" icon="key">
    Required to add data sources in [AI Training → Data Sources](https://platform.open.cx/data-sources).
  </Accordion>
</AccordionGroup>

## Set up the sync

<Steps>
  <Step title="Open Data Sources">
    Go to [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
  </Step>

  <Step title="Add a Shopify source">
    Click **Add source → Shopify**. You'll see a **Redirect URL** — copy it and paste it into your Shopify custom app's **Allowed redirection URL** list.
  </Step>

  <Step title="Enter your custom app credentials">
    | Field | Example | Where to get it |
    | - | - | - |
    | **Shop domain** | `your-store.myshopify.com` | Your store's `*.myshopify.com` domain. |
    | **Client ID** | — | From the Shopify custom app's **API credentials** page. |
    | **Client Secret** | — | Same page. |
  </Step>

  <Step title="Select streams">
    Pick which streams to sync. Pages is on by default; Articles and Products are opt-in. You can change the selection later — a re-auth is triggered to update scopes if you add a stream that needs a new one.
  </Step>

  <Step title="Authorize via OAuth">
    Click **Connect with Shopify**. A popup opens asking you to approve the scopes. Approve. When the popup closes, the source row shows **Active**.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Synced content appears under **Shopify**, grouped by stream. Pages and products include source URLs back to your storefront; articles don't carry a URL in the sync (Shopify's blog-article URLs require the blog handle, which isn't in the Airbyte data).
  </Step>
</Steps>

## Visibility rules

<AccordionGroup>
  <Accordion title="Pages and articles — by published_at" icon="eye">
    * `published_at` set → **public** (AI can cite in customer replies)
    * `published_at` null → **internal** (agent-facing surfaces only)
  </Accordion>

  <Accordion title="Products — by status" icon="tag">
    * `status === 'active'` → **public**
    * Any other status (draft, archived) → **internal**
  </Accordion>
</AccordionGroup>

## Limits

| | Value |
| - | - |
| **Streams synced** | `pages` (default), `articles` (opt-in), `products` (opt-in) |
| **Sync mode** | `incremental_append` per stream |
| **Sync cadence** | Airbyte polling — typically every few hours |
| **Credential type** | OAuth 2.0 via custom app (Client ID + Client Secret + shop) |
| **Multi-store** | One Shopify store per connection |
| **Product URLs** | Present via `handle` + shop domain |
| **Article URLs** | Not available in sync (blog handle missing) |
| **Draft / inactive content** | Synced as `internal` |

***

## Related Documentation

<CardGroup>
  <Card title="Shopify overview" icon="shopify" href="/knowledge/sources/shopify/overview">
    Knowledge vs. AI Actions.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/shopify/troubleshooting">
    Scope errors, missing streams, URLs.
  </Card>

  <Card title="Shopify integration" icon="cart-shopping" href="/integrations/shopify/overview">
    Admin API, order lookup, metadata.
  </Card>

  <Card title="AI Actions" icon="bolt" href="/integrations/shopify/ai-actions">
    Real-time tools against your store.
  </Card>
</CardGroup>


# Shopify
Source: https://docs.open.cx/knowledge/sources/shopify/overview

Sync Shopify pages, blog articles, and product descriptions into the AI training index.

<Note>
  This page covers **Shopify as a knowledge source** — syncing store content into the AI's training index. For **live order lookup, product search as tools, customer enrichment, and AI Actions**, see the [Shopify integration](/integrations/shopify/overview).
</Note>

The Shopify source pulls store content you publish through your storefront — pages, blog articles, and product descriptions — into the AI's training index. The AI reads this content for answers about policies, store information, and product details.

## Knowledge sync vs. live tools

This is the line most Shopify customers want clarified:

| You want the AI to… | Use |
| - | - |
| Answer from your shipping policy, return policy, About page, FAQ page | **Knowledge sync** (this source) — Pages stream |
| Answer from your blog posts | **Knowledge sync** — Articles stream |
| Answer from product descriptions at a general level | **Knowledge sync** — Products stream |
| Look up a specific customer's order status in real time | **[Shopify integration](/integrations/shopify/overview)** — Admin API AI Action |
| Search the live catalog for current pricing or stock | **[Shopify integration](/integrations/shopify/overview)** — AI Action |

Knowledge sync is for content that changes infrequently and you want the AI to know about. AI Actions are for real-time lookups.

## Per-stream opt-in

You pick which streams to sync when you connect:

* **Pages** (enabled by default) — store pages
* **Articles** (opt-in) — blog articles
* **Products** (opt-in) — product titles, descriptions, and metadata

Each stream requires a specific OAuth scope on your Shopify custom app.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Shopify" icon="plug" href="/knowledge/sources/shopify/connect">
    Custom app, OAuth, stream selection, scopes.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/shopify/troubleshooting">
    Scope errors, missing content, product URLs.
  </Card>

  <Card title="Shopify integration" icon="cart-shopping" href="/integrations/shopify/overview">
    Admin API actions, order lookup, contact metadata.
  </Card>

  <Card title="AI Actions" icon="bolt" href="/integrations/shopify/ai-actions">
    Tools the AI runs against Shopify at runtime.
  </Card>
</CardGroup>


# Shopify troubleshooting
Source: https://docs.open.cx/knowledge/sources/shopify/troubleshooting

Start at the Shopify source row in Data Sources. OAuth errors appear there; for "stream missing" or visibility issues, open AI Instructions and filter by Shopify.

Start at the **Shopify** source row in [**Data Sources**](https://platform.open.cx/data-sources). OAuth errors appear there; for "stream missing" or visibility issues, open AI Instructions and filter by **Shopify**.

## Common scenarios

| Symptom | Likely cause | Fix |
| - | - | - |
| **OAuth popup errors or redirects to a blank page** | The **Allowed redirection URL** in your Shopify custom app doesn't match the Redirect URL shown in the connect dialog | Copy the exact Redirect URL from the OpenCX dashboard into your Shopify custom app settings, save, retry **Connect with Shopify**. |
| **Products stream is empty but I enabled it** | The custom app doesn't have `read_products` scope — OAuth succeeds but Shopify returns zero rows | In your Shopify custom app, add `read_products` to the **Admin API access scopes**, save, re-authorize in OpenCX. |
| **Articles sync but URLs aren't cited** | The Airbyte Shopify connector doesn't return the blog handle needed to build article URLs | Known limitation. The AI references articles by title when citing sources. For full URLs in citations, use the [Website crawler](/knowledge/sources/website/overview) against your public blog URL. |
| **An unpublished product is showing in public replies** | `status` on the product is set to `active` but it's not actually visible on the storefront (inventory, channel visibility, etc.) | Change the product status in Shopify to `draft` or `archived` — the next sync flips visibility to `internal`. Or override per-item in AI Instructions. |
| **Pages visibility looks wrong** | The page's `published_at` in Shopify controls visibility — publishing/unpublishing in Shopify admin may not have updated `published_at` as expected | Confirm `published_at` in Shopify. Publish the page, trigger a re-sync in OpenCX. |
| **Multi-store request** | One connection per store today | Add a second OpenCX organization per store, or wait for multi-store scoping (contact support if blocked). |
| **None of the above** | — | Contact support with the connection ID and a sample item URL. |

***

## Related Documentation

<CardGroup>
  <Card title="Connect Shopify" icon="plug" href="/knowledge/sources/shopify/connect">
    Re-check scopes and redirect URL.
  </Card>

  <Card title="Shopify overview" icon="shopify" href="/knowledge/sources/shopify/overview">
    Knowledge vs. AI Actions.
  </Card>

  <Card title="Shopify integration" icon="cart-shopping" href="/integrations/shopify/overview">
    Store connection and AI Actions.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for article URLs.
  </Card>
</CardGroup>


# Connect a website
Source: https://docs.open.cx/knowledge/sources/website/connect

| Field | Default | What it does | |-------|---------|--------------| | URL | — | Starting URL.

<Tip>
  Configure the crawler at [**AI Training → Data Sources**](https://platform.open.cx/data-sources) in the OpenCX dashboard.
</Tip>

## Set up the crawler

<Steps>
  <Step title="Open Data Sources">
    Go to [**AI Training → Data Sources**](https://platform.open.cx/data-sources).
  </Step>

  <Step title="Add a Website source">
    Click **Add source → Website**. Paste the URL you want to crawl (e.g. `https://help.yourcompany.com`).
  </Step>

  <Step title="Set scope">
    Configure the crawl before it runs. Defaults work for most teams — adjust only when you have a reason.

    | Field | Default | What it does |
    | - | - | - |
    | **URL** | — | Starting URL. The crawler follows links within the same domain. |
    | **Display name** | Extracted from domain | Label shown in Data Sources. |
    | **Page limit** | `100` | Maximum pages per crawl (1–5000). Set higher for large sites. |
    | **Include paths** | empty | Whitelist regex. If set, only URLs matching are crawled. Use for locale or section scoping (e.g. `*/en-us/*`). |
    | **Exclude paths** | empty | Blacklist regex. Crawl skips matching URLs (e.g. `/admin/*`). Binary file extensions are always excluded. |
    | **Crawl interval (hours)** | `168` (7 days) | Auto re-crawl cadence. Minimum `168`. Set to null for manual-only. Daily re-crawls can be enabled by the OpenCX team on request. |
    | **Auto-start crawl** | `true` | Runs the first crawl immediately on save. |
  </Step>

  <Step title="Watch the first crawl">
    The datasource row shows live counters: **total pages**, **new**, **updated**, **removed**, **unchanged**. First crawls on a large help center can take 10–30 minutes.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Crawled pages appear under the datasource name. Spot-check a known article.
  </Step>
</Steps>

## Scoping with include/exclude paths

The single most common setup mistake: letting the crawler index your marketing funnel, blog, or admin paths alongside your help center. Use include/exclude paths deliberately.

<AccordionGroup>
  <Accordion title="Restrict to a single language" icon="language">
    **Scenario:** Your help center has `/en-us/`, `/fr-fr/`, `/de-de/`, and the AI only replies in English.

    Set **Include paths** to `*/en-us/*`. Non-English pages are skipped. Change the value any time — the next crawl respects the new scope.

    <Note>
      Existing non-English pages from earlier crawls stay indexed. Remove them by navigating into the datasource and bulk-deleting them from the Pages view.
    </Note>
  </Accordion>

  <Accordion title="Skip sections that aren't help content" icon="ban">
    **Scenario:** `help.acme.com` also serves `/blog/`, `/careers/`, `/pricing/`. None of those belong in the AI index.

    Set **Exclude paths** to multiple regexes: `/blog/*`, `/careers/*`, `/pricing/*`. The crawl drops matches before extraction.
  </Accordion>

  <Accordion title="Crawl only one category" icon="filter">
    **Scenario:** You want only the billing category indexed, not the whole help center.

    Set **Include paths** to the category root: `*/billing/*`. Combine with a higher `page_limit` if the category is large.
  </Accordion>
</AccordionGroup>

## Page-level control

After the first crawl completes, open the datasource detail view. You get per-page controls:

* **Exclude page** — the page stays in the list but won't re-sync. Use for one-off stale content.
* **Re-include page** — undo the above.
* **Delete page** — remove from the AI index. Optionally also deletes the underlying training item.
* **Resync page** — force a fresh fetch + re-index for one URL.

Bulk select multiple pages before triggering any of these.

## Limits

| | Value |
| - | - |
| **Streams synced** | Markdown extraction of main content (navigation/chrome excluded automatically) |
| **Sync mode** | Incremental — SHA-256 content hash per page; unchanged pages skipped |
| **Sync cadence** | `crawl_interval_hours` (default `168` / 7 days, min `168`, nullable for manual-only) |
| **Credential type** | None — public URLs only |
| **Multi-domain** | One datasource per domain. Add a second datasource for a different domain. |
| **Max pages per crawl** | 5000 (default 100) |
| **JavaScript rendering** | Firecrawl renders most SPAs, but client-only sites with heavy auth or lazy-loaded content may under-capture. Spot-check after the first crawl. |
| **Auth-gated content** | Not supported |

***

## Related Documentation

<CardGroup>
  <Card title="Website overview" icon="globe" href="/knowledge/sources/website/overview">
    What the crawler does and when to use it.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/website/troubleshooting">
    Stuck crawls, missing pages, dedup issues.
  </Card>

  <Card title="Crawl API" icon="code" href="/api-reference/crawl">
    Full REST API for datasources, crawls, pages.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources compared.
  </Card>
</CardGroup>


# Website
Source: https://docs.open.cx/knowledge/sources/website/overview

The Website source crawls a domain you control and ingests its pages into the AI's training index.

The **Website** source crawls a domain you control and ingests its pages into the AI's training index. Use it when the content you want the AI to know about is reachable at a public URL — a help center, a product docs site, a marketing pages surface — and you don't have a direct integration for the system that serves it.

## When to use the crawler vs a direct integration

| Situation | Use |
| - | - |
| You publish your help center through Zendesk, Intercom, or Front | The dedicated [Zendesk](/knowledge/sources/zendesk/overview) / [Intercom](/knowledge/sources/intercom/overview) / [Front](/knowledge/sources/front/overview) source |
| Your content lives in Confluence, Notion, GitBook, or Freshdesk | The dedicated source for that tool |
| Your content is reachable at a public URL and nothing above applies | The crawler |
| The site is gated behind auth | Not today — the crawler only fetches public URLs |

<Warning>
  Don't run both. If you've already connected Zendesk (or any other direct source), don't also crawl the public help-center URL for the same content. The AI will double-index every article and surface duplicates in retrieval.
</Warning>

## What the crawler does

* Kicks off a crawl against the URL you provide.
* Follows links within the domain up to `page_limit` pages (default **100**, max **5000**).
* Extracts main content as Markdown, skipping navigation chrome and binary assets.
* Tracks a content hash per page — re-crawls only re-index pages whose content changed.
* Re-runs on a schedule you pick (`crawl_interval_hours`, default and minimum **168 hours / 7 days**). Daily re-crawls can be enabled by the OpenCX team on request.
* Exposes every discovered page so you can exclude individual URLs, re-include ones you excluded, or force-resync one page.

***

## Related Documentation

<CardGroup>
  <Card title="Connect a website" icon="plug" href="/knowledge/sources/website/connect">
    URL, limits, include/exclude paths, crawl interval.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/website/troubleshooting">
    Stuck crawls, locale scoping, pages not indexing.
  </Card>

  <Card title="Crawl API" icon="code" href="/api-reference/crawl">
    Programmatic control of datasources, crawls, and pages.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    Decision matrix for all sources.
  </Card>
</CardGroup>


# Website troubleshooting
Source: https://docs.open.cx/knowledge/sources/website/troubleshooting

Start at the datasource row in Data Sources: it shows current status, last crawl timestamps, and an error message if the latest crawl failed.

Start at the datasource row in [**Data Sources**](https://platform.open.cx/data-sources): it shows current status, last crawl timestamps, and an error message if the latest crawl failed.

<Tip>
  For most issues, open the datasource detail view — the **Crawl history** section and the per-page list are where the signal is. Don't delete and re-create the datasource before checking those.
</Tip>

## Common scenarios

| Symptom | Likely cause | Fix |
| - | - | - |
| **Crawl has been "In Progress" for hours, no counters moving** | Firecrawl pipeline stall or webhook delivery lost | Open the datasource → **Cancel crawl**, then **Start crawl** again. If it recurs, file a ticket with the datasource ID — the back-end crawl jobs are traceable. |
| **AI cites non-English pages even after adding an English-only filter** | Old pages from before the filter change are still indexed | Open the datasource → **Pages** view → filter by language or URL pattern → bulk **Delete**. The next crawl respects the new filter going forward. |
| **AI answers from blog/funnel pages that shouldn't be in the index** | `exclude_paths` is empty or too narrow | Add the section regex to **Exclude paths** (e.g. `/blog/*`, `/pricing/*`). Then bulk-delete existing indexed pages that match from the Pages view. |
| **Some articles are missing after the crawl** | `page_limit` hit (default 100), paths blocked by `include_paths`, or pages require JS rendering for content | Raise `page_limit`. Remove over-narrow `include_paths`. For JS-heavy pages, spot-check by hitting a single page's **Resync** — if it comes back empty, the page isn't renderable by the crawler and needs a different source. |
| **AI surfaces the same article twice** | Both the crawler and a direct integration (Zendesk/Intercom/Front) are indexing the same content | Pick one. Disconnect the other. The direct integration is almost always the better choice for Help Center content — the crawler stays for other domains. |
| **Crawl completes but no pages synced** | The entry URL returned no links, or every link was blocked by `include_paths` / `exclude_paths` | Open a browser to the URL and confirm the page links out to the content you expect. Review `include_paths` — overly specific regexes filter out everything. |
| **None of the above** | — | Contact support with the datasource ID, approximate time of the issue, and a sample URL that's missing/wrong. |

## Limits at a glance

| | Value |
| - | - |
| **Page limit per crawl** | `1`–`5000` (default `100`) |
| **Minimum crawl interval** | `168` hours (7 days). Daily re-crawls can be enabled by the OpenCX team on request. |
| **Default crawl interval** | `168` hours (7 days) |
| **Binary file types** | Always excluded |
| **Auth-gated URLs** | Not supported |
| **JavaScript rendering** | Best effort via Firecrawl — not guaranteed for heavy SPAs |

***

## Related Documentation

<CardGroup>
  <Card title="Connect a website" icon="plug" href="/knowledge/sources/website/connect">
    Re-check URL, limits, include/exclude paths.
  </Card>

  <Card title="Website overview" icon="globe" href="/knowledge/sources/website/overview">
    When to use the crawler vs a direct integration.
  </Card>

  <Card title="Crawl API" icon="code" href="/api-reference/crawl">
    Programmatic exclude/include/resync.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    Switch to a direct integration if one fits.
  </Card>
</CardGroup>


# Connect Zendesk
Source: https://docs.open.cx/knowledge/sources/zendesk/connect

Paste your Zendesk subdomain, admin email, and API token — OpenCX pulls your Help Center articles.

<Tip>
  Configure the source at [**AI Training → Data Sources**](https://platform.open.cx/data-sources). This is separate from the [Ticketing integration](/integrations/zendesk/ticketing-api), though you can reuse the same API token.
</Tip>

## Set up the sync

<Steps>
  <Step title="Open Data Sources">
    Go to [**AI Training → Data Sources**](https://platform.open.cx/data-sources) in the OpenCX dashboard.
  </Step>

  <Step title="Add a Zendesk source">
    Click **Add source → Zendesk**. Paste the credentials below (each field label and placeholder mirrors the dashboard form).

    | Field | Example | Where to get it |
    | - | - | - |
    | **Subdomain** | `your-company` (from `company.zendesk.com`) | The instance name, not the public Help Center URL. |
    | **Email** | `admin@company.com` | The Zendesk user email the API token belongs to. |
    | **API Token** | `••••••••` | [Learn how to create an API token](https://developer.zendesk.com/api-reference/introduction/security-and-auth/). Any admin-level token with read access works. |

    <Note>
      You can reuse the API token from the [Ticketing integration](/integrations/zendesk/ticketing-api). The token just needs to be able to read Help Center articles.
    </Note>
  </Step>

  <Step title="Start the sync">
    Click **Connect**. The first run pulls every article across every locale — minutes to a few hours depending on catalog size.
  </Step>

  <Step title="Verify in AI Instructions">
    Open [**AI Training → AI Instructions**](https://platform.open.cx/ai-instructions). Articles appear grouped under **Zendesk**. Filter by visibility to confirm the eye icon matches expectations — see the visibility rules below.
  </Step>
</Steps>

## What gets synced

<AccordionGroup>
  <Accordion title="All article variants, across every locale" icon="layer-group">
    Published, <Tooltip>draft</Tooltip>, and <Tooltip>archived</Tooltip> articles are all fetched. Each locale is stored as its own entry so the AI answers in the right language.
  </Accordion>

  <Accordion title="Visibility is derived automatically" icon="eye">
    Every synced article is tagged **public** or **internal** based on Zendesk's own signals. This mirrors Zendesk's access model — you don't configure it twice.

    | Article state in Zendesk | Visibility in OpenCX |
    | - | - |
    | Published with no user-segment restriction | **Public** — AI cites it in customer replies |
    | Restricted to a <Tooltip>user segment</Tooltip> | **Internal** — AI uses it only in agent-facing surfaces, never in customer replies |
    | Draft | **Internal** — same as above |

    The eye icon in AI Instructions shows the final visibility. Override per-article if you need to.
  </Accordion>

  <Accordion title="Incremental sync on updated_at" icon="arrows-rotate">
    After the initial pull, only articles whose `updated_at` changed since the last run are fetched. Outdated articles marked `outdated: true` in Zendesk are filtered out before ingestion.
  </Accordion>
</AccordionGroup>

## Re-sync, disconnect, and re-connect

* **Sync now** on the source row pulls only articles changed since the last run. Use after a bulk edit in Zendesk.
* **Remove** on the source row deletes the connection and the synced items. The articles in Zendesk aren't touched.
* Re-adding the source re-pulls everything from scratch.

## Limits

| | Value |
| - | - |
| **Streams synced** | `articles` (includes `all_article_variants` — drafts, archived, published) |
| **Sync mode** | `incremental_deduped_history` on `updated_at` |
| **Sync cadence** | Airbyte polling — typically every few hours, configurable on the connection schedule |
| **Credential type** | Subdomain + admin email + API token (no OAuth) |
| **Multi-Help-Center** | **Not supported today.** One Help Center per Zendesk account is synced. |
| **Archived articles** | Fetched; show as `INTERNAL` unless also a draft. Delete in Zendesk to remove. |
| **Selective scoping** | **Not supported today.** Whole Help Center syncs. Use [Website crawler](/knowledge/sources/website/overview) with `include_paths` if you need to scope to a subset. |

***

## Related Documentation

<CardGroup>
  <Card title="Zendesk overview" icon="headset" href="/knowledge/sources/zendesk/overview">
    Scope and dual-presence context.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/zendesk/troubleshooting">
    Auth failures, visibility surprises, archived content.
  </Card>

  <Card title="Zendesk integration" icon="ticket" href="/integrations/zendesk/overview">
    Ticketing, Sunshine, channels.
  </Card>
</CardGroup>


# Zendesk
Source: https://docs.open.cx/knowledge/sources/zendesk/overview

The Zendesk source pulls your Help Center articles into the AI's training index.

<Note>
  This page covers **Zendesk as a knowledge source** — syncing Help Center articles into the AI's training index so replies cite your published content. For **ticketing, Sunshine, channels, and handoff**, see the [Zendesk integration](/integrations/zendesk/overview).
</Note>

The Zendesk source pulls your <Tooltip>Help Center</Tooltip> articles into the AI's training index. The AI retrieves from them at answer time and can cite them as sources. Sync is <Tooltip>incremental</Tooltip> — edits and new articles show up on the next scheduled run.

## What you're signing up for

* **Articles only.** No tickets, users, or organizations. This connector is strictly for training content.
* **All variants.** Published, draft, and archived articles are all fetched. Visibility in OpenCX is derived automatically — see the [Connect](/knowledge/sources/zendesk/connect) page.
* **Every locale.** Articles in each language are synced as separate entries. The AI answers in the language it retrieves from.
* **One Help Center per connection.** If your Zendesk account hosts multiple Help Centers under one API token, only one is synced today.

## Common stumbling blocks

<Warning>
  **The Zendesk source connects to a Zendesk instance via the Support API — it's not a public Help Center crawler.** The **Subdomain** field is your Zendesk instance name (e.g. `acme` from `acme.zendesk.com`), not your public Help Center URL (e.g. `help.acme.com`). If you paste the public URL, the sync will fail with an authentication error.
</Warning>

If you're trying to index a public help center and don't have Zendesk admin credentials, use the [Website crawler](/knowledge/sources/website/overview) against the public URL instead.

***

## Related Documentation

<CardGroup>
  <Card title="Connect Zendesk" icon="plug" href="/knowledge/sources/zendesk/connect">
    Subdomain, API token, visibility rules.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/knowledge/sources/zendesk/troubleshooting">
    Sync failures, segment surprises, archived articles.
  </Card>

  <Card title="Zendesk integration" icon="headset" href="/integrations/zendesk/overview">
    Ticketing, Sunshine, channels.
  </Card>

  <Card title="Connect a knowledge source" icon="brain" href="/knowledge/sources/overview">
    All sources compared.
  </Card>
</CardGroup>


# Zendesk troubleshooting
Source: https://docs.open.cx/knowledge/sources/zendesk/troubleshooting

Start at the Zendesk source row in Data Sources. If the latest sync failed, the error message appears there. For incremental issues (missing articles, wrong visibility), check AI Instructions —…

Start at the **Zendesk** source row in [**Data Sources**](https://platform.open.cx/data-sources). If the latest sync failed, the error message appears there. For incremental issues (missing articles, wrong visibility), check **AI Instructions** — filter by the **Zendesk** source.

## Common scenarios

| Symptom | Likely cause | Fix |
| - | - | - |
| **Sync keeps failing; "could not authenticate" or 401** | The **Subdomain** field has the public Help Center URL (e.g. `help.yourcompany.com`) instead of the Zendesk instance name | Open the source, set **Subdomain** to just the instance name — `your-company` from `your-company.zendesk.com`. If you publish the Help Center on a custom domain, that custom domain is irrelevant — use the `*.zendesk.com` subdomain. |
| **Article is public in Zendesk but shows as Internal in OpenCX** | The article is assigned to a Zendesk <Tooltip>user segment</Tooltip> | Either remove the segment restriction in Zendesk (article visibility refreshes on next sync), or override the visibility per-article in [AI Instructions](https://platform.open.cx/ai-instructions) using the eye icon. |
| **Archived article still appears in AI answers** | Archived articles still sync today — they're indexed as `INTERNAL` but the AI can still cite them in agent-facing surfaces | Delete the article in Zendesk (the next sync removes it from OpenCX), or bulk-delete from the Zendesk folder in AI Instructions. Tracked as a known gap — see the limits table on the [Connect page](/knowledge/sources/zendesk/connect). |
| **One Zendesk account hosts multiple Help Centers — only one synced** | Not supported today. The Airbyte Zendesk source ingests articles across all Help Centers in the account without a per-HC filter. | Use the [Website crawler](/knowledge/sources/website/overview) against the Help Center you **don't** want Zendesk-synced, with the Zendesk source covering the primary one. Escalate to support if you need proper multi-HC scoping. |
| **Re-syncing doesn't pick up bulk edits** | Incremental sync cursors on `updated_at` — but bulk edits in Zendesk sometimes don't bump that field | Use **Sync now** on the source. If items are still stale, remove and re-add the source to force a full pull. |
| **None of the above** | — | Contact support with the source connection ID, a sample article URL, and what you expected vs. what you see. |

## Limits

| | Value |
| - | - |
| **Streams synced** | `articles` only |
| **Multi-Help-Center** | Not supported today |
| **Per-category/per-section scoping** | Not supported today |
| **Archived articles** | Still synced (marked internal) |
| **Sync cadence** | Airbyte polling — typically every few hours |
| **Credential fallback** | None — the subdomain + email + API token must be valid together |

***

## Related Documentation

<CardGroup>
  <Card title="Connect Zendesk" icon="plug" href="/knowledge/sources/zendesk/connect">
    Re-check credentials, visibility rules, limits.
  </Card>

  <Card title="Zendesk overview" icon="headset" href="/knowledge/sources/zendesk/overview">
    What this source does.
  </Card>

  <Card title="Zendesk integration" icon="ticket" href="/integrations/zendesk/overview">
    Ticketing and control surface.
  </Card>

  <Card title="Website crawler" icon="globe" href="/knowledge/sources/website/overview">
    Fallback for multi-HC scoping.
  </Card>
</CardGroup>


# Claude Code
Source: https://docs.open.cx/mcp/clients/claude-code

Set up and use the OpenCX MCP server in Claude Code — CLI commands, environment variables, scope, and automation.

Claude Code manages <Tooltip>MCP</Tooltip> servers through CLI commands instead of JSON config files. Servers can be scoped globally (all projects) or per-project.

## Setup

<Steps>
  <Step title="Set your API key">
    Add your [OpenCX API key](https://platform.open.cx/settings/access) to your shell profile so it persists across sessions:

    <Tabs>
      <Tab title="zsh (macOS)">
        ```bash theme={"dark"}
        echo 'export OPENCX_API_KEY="your-api-key-here"' >> ~/.zshrc
        source ~/.zshrc
        ```
      </Tab>

      <Tab title="bash (Linux)">
        ```bash theme={"dark"}
        echo 'export OPENCX_API_KEY="your-api-key-here"' >> ~/.bashrc
        source ~/.bashrc
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add the MCP server">
    ```bash theme={"dark"}
    claude mcp add opencx -- npx -y @opencx/mcp
    ```

    This registers the server at user scope (available in all projects) by default.

    <Tip>
      Prefer zero install? Connect to the [hosted endpoint](/mcp/install#remote-server-no-install) instead — same tools, nothing to keep updated:

      ```bash theme={"dark"}
      claude mcp add --transport http opencx https://api.open.cx/mcp \
        --header "Authorization: Bearer $OPENCX_API_KEY"
      ```
    </Tip>
  </Step>

  <Step title="Verify">
    Start Claude Code and ask: *"List my recent chat sessions."*

    You can also confirm the server is registered:

    ```bash theme={"dark"}
    claude mcp list
    ```
  </Step>
</Steps>

## Scope

Claude Code supports two scopes for MCP servers:

| Scope | Flag | Stored in | Shared with team |
| - | - | - | - |
| **User** (default) | `--scope user` | `~/.claude/` | No |
| **Project** | `--scope project` | `.mcp.json` in repo root | Yes (commit the file) |

Add at project scope when your team should share the same MCP setup:

```bash theme={"dark"}
claude mcp add opencx --scope project -- npx -y @opencx/mcp
```

<Note>
  Project-scoped servers read environment variables from the shell of whoever
  runs Claude Code. Each team member sets `OPENCX_API_KEY` in their own shell
  profile.
</Note>

## Managing Servers

```bash theme={"dark"}
claude mcp list                    # List all registered servers
claude mcp remove opencx           # Remove the server
claude mcp add opencx -- npx -y @opencx/mcp  # Re-add after removal
```

## CI and Automation

Claude Code can use MCP servers in non-interactive contexts. Pass the API key through CI secrets:

```bash theme={"dark"}
OPENCX_API_KEY=${{ secrets.OPENCX_API_KEY }} claude --print "List unresolved sessions from the last 24 hours"
```

For headless use, Claude Code's `--print` flag outputs the response to stdout without an interactive session.

***

## Related Documentation

<CardGroup>
  <Card title="Claude Desktop" icon="message-bot" href="/mcp/clients/claude-desktop">
    JSON config and app restart flow
  </Card>

  <Card title="Get Started" icon="download" href="/mcp/install">
    API key setup and all client configs
  </Card>

  <Card title="Prompt Library" icon="message" href="/mcp/prompts">
    Ready-to-use prompts by domain
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Claude Desktop
Source: https://docs.open.cx/mcp/clients/claude-desktop

Set up and use the OpenCX MCP server in Claude Desktop — config file locations, restart behavior, and multi-server setup.

Claude Desktop supports <Tooltip>MCP</Tooltip> servers through a JSON config file. The file location depends on your operating system.

<Warning>
  Claude Desktop must be **fully restarted** (quit and reopen, not just start a
  new conversation) after any config change. This is the most common setup
  issue.
</Warning>

## Setup

<Steps>
  <Step title="Open the config file">
    The config file location depends on your OS:

    <Tabs>
      <Tab title="macOS">
        ```
        ~/Library/Application Support/Claude/claude_desktop_config.json
        ```

        Open it in your editor, or run:

        ```bash theme={"dark"}
        open ~/Library/Application\ Support/Claude/claude_desktop_config.json
        ```
      </Tab>

      <Tab title="Windows">
        ```
        %APPDATA%\Claude\claude_desktop_config.json
        ```

        Open it in your editor, or press `Win+R` and paste the path above.
      </Tab>

      <Tab title="Linux">
        ```
        ~/.config/Claude/claude_desktop_config.json
        ```
      </Tab>
    </Tabs>

    If the file doesn't exist, create it.
  </Step>

  <Step title="Add the OpenCX server">
    Paste this into your config file:

    ```json theme={"dark"}
    {
      "mcpServers": {
        "opencx": {
          "command": "npx",
          "args": ["-y", "@opencx/mcp"],
          "env": {
            "OPENCX_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```

    Replace `your-api-key-here` with your [OpenCX API key](https://platform.open.cx/settings/access).

    <Tip>
      To use the [hosted endpoint](/mcp/install#remote-server-no-install) instead of running the server locally, bridge it with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) (Claude Desktop's connector UI doesn't support custom auth headers):

      ```json theme={"dark"}
      {
        "mcpServers": {
          "opencx": {
            "command": "npx",
            "args": [
              "-y",
              "mcp-remote",
              "https://api.open.cx/mcp",
              "--header",
              "Authorization: Bearer your-api-key-here"
            ]
          }
        }
      }
      ```
    </Tip>
  </Step>

  <Step title="Restart Claude Desktop">
    **Fully quit** Claude Desktop (not just close the window) and reopen it. On
    macOS, use `Cmd+Q`. On Windows, right-click the system tray icon and select
    **Quit**.
  </Step>

  <Step title="Verify">
    Look for the **hammer icon** in the chat input area. Click it to see connected MCP servers and available tools. Then ask: *"List my recent chat sessions."*
  </Step>
</Steps>

## The MCP Indicator

Once connected, a **hammer icon** appears next to the chat input. Click it to see:

* Which MCP servers are connected
* How many tools are available
* Individual tool names (click to expand)

If the hammer icon doesn't appear, the config file isn't being read. Double-check the file path and restart Claude Desktop.

## Multiple MCP Servers

Add other MCP servers alongside OpenCX in the same `mcpServers` object:

```json theme={"dark"}
{
  "mcpServers": {
    "opencx": {
      "command": "npx",
      "args": ["-y", "@opencx/mcp"],
      "env": {
        "OPENCX_API_KEY": "your-opencx-key"
      }
    },
    "another-server": {
      "command": "npx",
      "args": ["-y", "@another/mcp-server"],
      "env": {
        "API_KEY": "your-other-key"
      }
    }
  }
}
```

Each server runs as a separate process. Claude Desktop makes tools from all connected servers available in every conversation.

## Common Issues

| Symptom | Fix |
| - | - |
| Hammer icon missing | Check config file path and JSON syntax. Restart Claude Desktop fully. |
| Tools appear but fail with 401 | API key is invalid or revoked. Generate a new one in your [dashboard](https://platform.open.cx/settings/access). |
| "Server disconnected" after idle | Claude Desktop may stop idle MCP servers. Start a new conversation to reconnect. |

***

## Related Documentation

<CardGroup>
  <Card title="Claude Code" icon="terminal" href="/mcp/clients/claude-code">
    CLI-based MCP setup in the same Claude family
  </Card>

  <Card title="Get Started" icon="download" href="/mcp/install">
    API key setup and all client configs
  </Card>

  <Card title="Prompt Library" icon="message" href="/mcp/prompts">
    Ready-to-use prompts by domain
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Cursor
Source: https://docs.open.cx/mcp/clients/cursor

Set up and use the OpenCX MCP server in Cursor — project vs global config, agent mode, and debugging.

Cursor supports <Tooltip>MCP</Tooltip> servers natively. You can configure OpenCX at the project level (shared with your team) or globally (for your machine only).

<Warning>
  MCP tools only work in **Agent mode**. If you're in Ask mode, Cursor won't
  call any tools. Switch to Agent mode before testing.
</Warning>

## Setup

<Steps>
  <Step title="Open MCP settings">
    Go to **Cursor Settings > MCP** and click **Add new global MCP server** (or **Add new project MCP server** for project-scoped config).
  </Step>

  <Step title="Paste the config">
    ```json theme={"dark"}
    {
      "mcpServers": {
        "opencx": {
          "command": "npx",
          "args": ["-y", "@opencx/mcp"],
          "env": {
            "OPENCX_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```

    Replace `your-api-key-here` with your [OpenCX API key](https://platform.open.cx/settings/access).

    <Tip>
      Prefer zero install? Use the [hosted endpoint](/mcp/install#remote-server-no-install) instead — same tools, no Node.js required:

      ```json theme={"dark"}
      {
        "mcpServers": {
          "opencx": {
            "url": "https://api.open.cx/mcp",
            "headers": {
              "Authorization": "Bearer your-api-key-here"
            }
          }
        }
      }
      ```
    </Tip>
  </Step>

  <Step title="Verify">
    Open a new Agent mode chat and ask: *"List my recent chat sessions."*

    If you get results, the server is connected.
  </Step>
</Steps>

## Project vs Global Config

| Scope | File | Shared with team | Use when |
| - | - | - | - |
| **Project** | `.cursor/mcp.json` in repo root | Yes (commit the file) | Team shares the same MCP setup |
| **Global** | `~/.cursor/mcp.json` | No | Personal tools across all projects |

<Note>
  When using project-scoped config, reference `OPENCX_API_KEY` as an environment
  variable in the `env` block — don't hardcode the key in a committed file. Each
  team member sets the key in their local shell profile or `.env`.
</Note>

## Agent Mode vs Ask Mode

Cursor has two chat modes:

* **Agent mode** — can call MCP tools, read/write files, run commands. This is where OpenCX tools work.
* **Ask mode** — read-only, no tool calls. MCP tools are unavailable.

If your prompts aren't triggering OpenCX tools, check the mode toggle at the top of the chat panel.

## Debugging

If the server isn't connecting or tools aren't appearing:

1. **Check the MCP panel** — go to **Cursor Settings > MCP**. Each server shows a status indicator (green = connected, red = error). Click the server name to see logs.
2. **Restart the server** — click the refresh icon next to the server name in the MCP panel.
3. **Check the output** — Cursor shows MCP tool calls and responses inline in the chat. If a tool call fails, the error message appears in the response.
4. **Verify Node.js** — run `node --version` in Cursor's terminal. The MCP server requires Node.js 18+.

***

## Related Documentation

<CardGroup>
  <Card title="Get Started" icon="download" href="/mcp/install">
    API key setup and all client configs
  </Card>

  <Card title="VS Code" icon="code" href="/mcp/clients/vscode">
    mcp.json and Copilot Chat
  </Card>

  <Card title="Prompt Library" icon="message" href="/mcp/prompts">
    Ready-to-use prompts by domain
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Visual Studio Code
Source: https://docs.open.cx/mcp/clients/vscode

Set up and use the OpenCX MCP server in Visual Studio Code with GitHub Copilot and mcp.json.

Visual Studio Code supports <Tooltip>MCP</Tooltip> servers through a dedicated `mcp.json` file. MCP tools are available when you use **GitHub Copilot** agent features (Copilot Chat with tool use).

<Note>
  You need [GitHub Copilot](https://github.com/features/copilot) and a recent VS
  Code build with MCP support. See [Add and manage MCP servers in VS
  Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
  for the latest UI flows.
</Note>

## Setup

<Steps>
  <Step title="Open MCP configuration">
    Open the Command Palette (**Shift+Command+P** on macOS, **Ctrl+Shift+P** on Windows or Linux) and run **MCP: Open User Configuration** for a personal server, or **MCP: Open Workspace Folder MCP Configuration** to store config in `.vscode/mcp.json` for the current project.
  </Step>

  <Step title="Add the OpenCX server">
    Paste this into `mcp.json`:

    ```json theme={"dark"}
    {
      "servers": {
        "opencx": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@opencx/mcp"],
          "env": {
            "OPENCX_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```

    Replace `your-api-key-here` with your [OpenCX API key](https://platform.open.cx/settings/access).

    For secrets you prefer not to store in the file, use [input variables](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration) (for example `${input:opencx-api-key}`) and define the corresponding `inputs` entry in the same `mcp.json`.

    <Tip>
      Prefer zero install? Use the [hosted endpoint](/mcp/install#remote-server-no-install) instead — same tools, no Node.js required:

      ```json theme={"dark"}
      {
        "servers": {
          "opencx": {
            "type": "http",
            "url": "https://api.open.cx/mcp",
            "headers": {
              "Authorization": "Bearer your-api-key-here"
            }
          }
        }
      }
      ```
    </Tip>
  </Step>

  <Step title="Trust and start the server">
    When VS Code starts the server for the first time, confirm any trust prompts.
    Use the **MCP: List Servers** command to see status, logs, and restart
    options.
  </Step>

  <Step title="Verify in Copilot Chat">
    Open Copilot Chat in agent mode and ask: *"List my recent chat sessions."*
  </Step>
</Steps>

## Workspace vs user config

| Location | Path | Best for |
| - | - | - |
| **Workspace** | `.vscode/mcp.json` | Team-shared setup (omit secrets from git; use inputs or `envFile`) |
| **User** | Opened via **MCP: Open User Configuration** | Personal OpenCX access across all folders |

## Debugging

1. Run **MCP: List Servers** and select **opencx** to view output and errors.
2. Confirm **Node.js 18+** is on your PATH in the same environment VS Code uses (`node --version` in the integrated terminal).
3. If tools never appear, confirm Copilot Chat is using a model and mode that supports tools (see [Use agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode)).

***

## Related Documentation

<CardGroup>
  <Card title="Get Started" icon="download" href="/mcp/install">
    API key setup and all client configs
  </Card>

  <Card title="Cursor" icon="text-slash" href="/mcp/clients/cursor">
    Similar editor-native MCP setup
  </Card>

  <Card title="Prompt Library" icon="message" href="/mcp/prompts">
    Ready-to-use prompts by domain
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Windsurf
Source: https://docs.open.cx/mcp/clients/windsurf

Set up and use the OpenCX MCP server in Windsurf — MCP settings and JSON configuration.

Windsurf supports <Tooltip>MCP</Tooltip> servers through **`mcp_config.json`**, which Cascade reads when you use MCP tools. See [Cascade MCP integration](https://docs.windsurf.com/windsurf/cascade/mcp) in the Windsurf docs for the latest UI.

## Setup

<Steps>
  <Step title="Open the config file">
    From the Command Palette (**Shift+Command+P** / **Ctrl+Shift+P**), run **Windsurf: Configure MCP Servers**, or edit the file directly:

    * **macOS / Linux:** `~/.codeium/windsurf/mcp_config.json`
    * **Windows:** `%USERPROFILE%\.codeium\windsurf\mcp_config.json`

    You can also open it from the **MCPs** menu in the Cascade panel, then choose the option to view or edit the raw config.
  </Step>

  <Step title="Add the OpenCX server">
    Use the same structure as in [Get Started](/mcp/install) under the **Windsurf** tab:

    ```json theme={"dark"}
    {
      "mcpServers": {
        "opencx": {
          "command": "npx",
          "args": ["-y", "@opencx/mcp"],
          "env": {
            "OPENCX_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```

    Replace `your-api-key-here` with your [OpenCX API key](https://platform.open.cx/settings/access).
  </Step>

  <Step title="Restart and verify">
    Fully quit and reopen Windsurf so Cascade picks up changes. In Cascade, ask: *"List my recent chat sessions."*
  </Step>
</Steps>

## Tips

* Keep the API key out of shared repos. Windsurf supports interpolation such as `${env:OPENCX_API_KEY}` in `command`, `args`, and `env` fields so you can read the key from your shell environment instead of pasting it into the file.
* If the server fails to start, run `npx -y @opencx/mcp` in a terminal to confirm Node and network access.

***

## Related Documentation

<CardGroup>
  <Card title="Get Started" icon="download" href="/mcp/install">
    API key setup and all client configs
  </Card>

  <Card title="Cursor" icon="text-slash" href="/mcp/clients/cursor">
    Similar mcpServers JSON shape
  </Card>

  <Card title="VS Code" icon="code" href="/mcp/clients/vscode">
    Microsoft editor MCP via mcp.json
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Zed
Source: https://docs.open.cx/mcp/clients/zed

Set up and use the OpenCX MCP server in Zed — context_servers in settings and the Agent panel.

Zed connects to <Tooltip>MCP</Tooltip> servers through the `context_servers` key in your settings. Tools are used from the **Agent** panel when a compatible model is selected.

<Note>
  Zed's MCP format evolves between releases. For the authoritative schema, see [Model Context Protocol](https://zed.dev/docs/ai/mcp.html) in the Zed documentation.
</Note>

## Setup

<Steps>
  <Step title="Open Zed settings">
    Run **zed: open settings** from the command palette, or edit your user `settings.json` (for example `~/.config/zed/settings.json` on Linux, or the path shown in Zed's settings UI on macOS and Windows).
  </Step>

  <Step title="Add OpenCX under context_servers">
    Add an `opencx` entry (merge with any existing `context_servers` object):

    ```json theme={"dark"}
    {
      "context_servers": {
        "opencx": {
          "command": "npx",
          "args": ["-y", "@opencx/mcp"],
          "env": {
            "OPENCX_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```

    Replace `your-api-key-here` with your [OpenCX API key](https://platform.open.cx/settings/access).
  </Step>

  <Step title="Confirm in the Agent panel">
    Open the Agent panel settings view and check that **opencx** shows a healthy status indicator. Then ask the agent: *"List my recent chat sessions."*
  </Step>
</Steps>

## Project-level config

You can also define MCP servers in **`.zed/settings.json`** inside a project so the team shares the same server list. Do not commit real API keys; document how each developer sets `OPENCX_API_KEY` locally.

## Tool approval

Zed may prompt before running MCP tools. Adjust tool permissions in Zed settings if you want stricter or more permissive defaults for trusted servers.

***

## Related Documentation

<CardGroup>
  <Card title="Get Started" icon="download" href="/mcp/install">
    API key setup and all client configs
  </Card>

  <Card title="Cursor" icon="text-slash" href="/mcp/clients/cursor">
    Another editor-native MCP workflow
  </Card>

  <Card title="Prompt Library" icon="message" href="/mcp/prompts">
    Ready-to-use prompts by domain
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Mcp get started
Source: https://docs.open.cx/mcp/install

Add the OpenCX MCP server to Claude Desktop, Cursor, VS Code, Windsurf, or Claude Code — from API key to first query in minutes.

Add the OpenCX <Tooltip>MCP</Tooltip> server to your AI client so it can manage contacts, sessions, training, and more through natural language.

<Tip>
  Fastest path: add `https://api.open.cx/mcp` to your client and sign in — no
  API key to create or rotate. See [Connect with your OpenCX
  sign-in](#connect-with-your-opencx-sign-in) below.
</Tip>

**Prerequisites:** for the sign-in setup, an OpenCX account. For the API-key setups below, an OpenCX API key (created below) and Node.js 18+ for the local `npx` option.

<Steps>
  <Step title="Create an API key">
    Open your [OpenCX dashboard](https://platform.open.cx/settings/access) and navigate to **Settings > API Keys > Create API Key**. Give it a descriptive name (e.g. "Cursor MCP") and copy the key immediately — it is only shown once.
  </Step>

  <Step title="Add to your AI client">
    Paste the configuration below into your client's MCP settings. Replace `your-api-key-here` with the key you just copied.

    <CodeGroup>
      ```json Claude Desktop theme={"dark"}
      {
        "mcpServers": {
          "opencx": {
            "command": "npx",
            "args": ["-y", "@opencx/mcp"],
            "env": {
              "OPENCX_API_KEY": "your-api-key-here"
            }
          }
        }
      }
      ```

      ```json Cursor theme={"dark"}
      {
        "mcpServers": {
          "opencx": {
            "command": "npx",
            "args": ["-y", "@opencx/mcp"],
            "env": {
              "OPENCX_API_KEY": "your-api-key-here"
            }
          }
        }
      }
      ```

      ```json VS Code theme={"dark"}
      {
        "servers": {
          "opencx": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@opencx/mcp"],
            "env": {
              "OPENCX_API_KEY": "your-api-key-here"
            }
          }
        }
      }
      ```

      ```json Windsurf theme={"dark"}
      {
        "mcpServers": {
          "opencx": {
            "command": "npx",
            "args": ["-y", "@opencx/mcp"],
            "env": {
              "OPENCX_API_KEY": "your-api-key-here"
            }
          }
        }
      }
      ```

      ```bash Claude Code theme={"dark"}
      export OPENCX_API_KEY="your-api-key-here"
      claude mcp add opencx -- npx -y @opencx/mcp
      ```
    </CodeGroup>

    <Note>
      Each client has its own config file and UI. See [Cursor](/mcp/clients/cursor), [Claude Desktop](/mcp/clients/claude-desktop), [Claude Code](/mcp/clients/claude-code), [VS Code](/mcp/clients/vscode), [Windsurf](/mcp/clients/windsurf), and [Zed](/mcp/clients/zed).
    </Note>
  </Step>

  <Step title="Verify the connection">
    Ask your AI assistant one of these prompts to confirm the server is connected:

    * *"List my recent chat sessions"*
    * *"Show me CSAT scores from the last week"*
    * *"Search my knowledge base for refund policy"*

    If you get results back, the connection is working.
  </Step>
</Steps>

## Connect with your OpenCX sign-in

The hosted endpoint also accepts your own OpenCX sign-in, so a teammate can connect a client without anyone creating or sharing an API key. It is the same URL as the API-key setup — what differs is that you leave the `Authorization` header off.

<Steps>
  <Step title="Add the server to your client">
    Add `https://api.open.cx/mcp` as a remote (Streamable HTTP) server with **no** `Authorization` header — that header is what suppresses the sign-in. The client registers itself and opens a browser window.

    <CodeGroup>
      ```bash Claude Code theme={"dark"}
      claude mcp add --transport http opencx https://api.open.cx/mcp
      ```

      ```json Cursor / Claude Desktop theme={"dark"}
      {
        "mcpServers": {
          "opencx": {
            "type": "http",
            "url": "https://api.open.cx/mcp"
          }
        }
      }
      ```

      ```json VS Code theme={"dark"}
      {
        "servers": {
          "opencx": {
            "type": "http",
            "url": "https://api.open.cx/mcp"
          }
        }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Sign in and pick an organization">
    Sign in to OpenCX if you are not already, choose which organization the app may work in, and select **Connect**. The client is connected from that point on and refreshes access by itself.

    To skip the choice, copy the server URL from **Settings > API Keys > Connected apps** instead. It ends in `?org=<your organization id>`, so that organization is already selected when you sign in. You can still switch to another one before connecting, and some clients may ask you to choose anyway.

    Connecting to a second organization is the same URL again under a different server name — each connection is approved separately.
  </Step>
</Steps>

**What the client can do:** exactly what your own role lets you do, nothing more. Permissions are re-checked on every request, so narrowing someone's role — or removing them from the organization — takes effect immediately, with no reconnection and no key to revoke.

**Disconnecting:** open **Settings > API Keys > Connected apps** in the organization and choose **Disconnect**. Access stops at once. Each teammate sees and manages only their own connections.

<Note>
  Clients that cannot open a browser (headless CI, servers, scripts) should keep using an API key — see [Remote server](#remote-server-no-install) below.
</Note>

## Remote server (no install)

OpenCX also hosts the MCP server over <Tooltip>Streamable HTTP</Tooltip> at `https://api.open.cx/mcp`. Nothing to install or keep updated — authenticate with the same API key as a bearer token:

<CodeGroup>
  ```bash Claude Code theme={"dark"}
  claude mcp add --transport http opencx https://api.open.cx/mcp \
    --header "Authorization: Bearer your-api-key-here"
  ```

  ```json Cursor / Claude Desktop theme={"dark"}
  {
    "mcpServers": {
      "opencx": {
        "type": "http",
        "url": "https://api.open.cx/mcp",
        "headers": {
          "Authorization": "Bearer your-api-key-here"
        }
      }
    }
  }
  ```

  ```json VS Code theme={"dark"}
  {
    "servers": {
      "opencx": {
        "type": "http",
        "url": "https://api.open.cx/mcp",
        "headers": {
          "Authorization": "Bearer your-api-key-here"
        }
      }
    }
  }
  ```
</CodeGroup>

The remote and local servers expose the same tools; pick whichever fits your environment. Self-hosted deployments serve the same endpoint at `https://your-instance/mcp`.

## Authentication

The hosted endpoint accepts either:

* **your OpenCX sign-in**, for a client you use yourself — you pick the organization when you approve it, the connection carries your permissions, and it is managed from **Settings > API Keys > Connected apps**;
* **an organization API key**, for servers, CI and scripts — the key carries the scopes you gave it, independently of any person.

Both reach the same tools. Organization API keys are unaffected by the sign-in option and keep working exactly as before.

The local `npx` server authenticates with a per-organization API key passed through the `OPENCX_API_KEY` environment variable.

| Variable | Required | Default | Description |
| - | - | - | - |
| `OPENCX_API_KEY` | Yes | — | Your OpenCX API key |
| `OPENCX_BASE_URL` | No | `https://api.open.cx` | API base URL for self-hosted deployments |

**Rotating keys:** Create a new key in **Settings > API Keys**, update your MCP client config, then delete the old key from the dashboard.

<Warning>
  Never commit API keys to version control. Use your local MCP client config
  file or CI secrets for automated environments.
</Warning>

## Self-hosted instances

If you run a self-hosted OpenCX deployment, set `OPENCX_BASE_URL` to your instance URL. The server requires HTTPS unless targeting `localhost` for local development.

***

## Related Documentation

<CardGroup>
  <Card title="Prompt Library" icon="message" href="/mcp/prompts">
    Ready-to-use prompts by domain
  </Card>

  <Card title="Cursor" icon="text-slash" href="/mcp/clients/cursor">
    Project config, agent mode, debugging
  </Card>

  <Card title="VS Code" icon="code" href="/mcp/clients/vscode">
    mcp.json and Copilot
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Debug connection and authentication issues
  </Card>
</CardGroup>


# MCP overview
Source: https://docs.open.cx/mcp/introduction

Connect AI coding tools to your OpenCX account — manage sessions, train your agent, trigger workflows, and review analytics through natural language.

The OpenCX <Tooltip>MCP</Tooltip> server connects your account to AI clients like [Cursor](/mcp/clients/cursor), [Claude Desktop](/mcp/clients/claude-desktop), [Claude Code](/mcp/clients/claude-code), [Visual Studio Code](/mcp/clients/vscode), [Windsurf](/mcp/clients/windsurf), and [Zed](/mcp/clients/zed). Manage contacts, sessions, training, workflows, and analytics through natural language — without switching to the dashboard.

<Tip>
  New here? Head to **[Get Started](/mcp/install)** to connect your first AI
  client.
</Tip>

## What You Can Do

<AccordionGroup>
  <Accordion title="Support inbox" icon="inbox">
    Pull session history, reassign conversations, resolve tickets, and reply — without leaving your editor. Filter by status, sentiment, tags, or team.
  </Accordion>

  <Accordion title="Train your AI agent" icon="brain">
    Create and edit training scenarios, search the knowledge base, organize
    training into directories, and crawl websites to keep content current.
  </Accordion>

  <Accordion title="Workflows and actions" icon="bolt">
    Configure API actions your AI agent calls during conversations. Trigger
    workflows, manage outbound sequences, and set up phone agents.
  </Accordion>

  <Accordion title="Analytics and insights" icon="chart-line">
    Review handoff reasons, CSAT scores, SLA compliance, and recurring support themes. Pull impact reports and customer insights by category.
  </Accordion>
</AccordionGroup>

## Three ways to connect

* **Sign-in (no install, no key)** — add `https://api.open.cx/mcp` to your client and sign in when it asks, picking the organization to connect. The connection carries your own permissions and you can disconnect it at any time. See [Connect with your OpenCX sign-in](/mcp/install#connect-with-your-opencx-sign-in).
* **Remote with an API key (no install)** — connect straight to `https://api.open.cx/mcp` over Streamable HTTP with your API key as a bearer token. Best for servers, CI and scripts that cannot open a browser. See [Remote server](/mcp/install#remote-server-no-install).
* **Local** — run the server yourself via `npx @opencx/mcp` (stdio). Works with every MCP client and self-hosted deployments.

All three expose the same tools.

## Requirements

* **An OpenCX account, or an API key** — sign-in connections need access to the organization; key-based setups need a key from your [OpenCX dashboard](https://platform.open.cx/settings/access) under **Settings > API Keys**
* **Node.js 18 or later** — only for the local `npx @opencx/mcp` setup; the remote endpoint needs nothing installed

***

## Related Documentation

<CardGroup>
  <Card title="Get Started" icon="download" href="/mcp/install">
    Connect the MCP server to your AI client
  </Card>

  <Card title="Prompt Library" icon="message" href="/mcp/prompts">
    Ready-to-use prompts by domain
  </Card>

  <Card title="Tools Reference" icon="toolbox" href="/mcp/tools">
    All available tools organized by domain
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Common issues and how to resolve them
  </Card>
</CardGroup>


# Prompt Library
Source: https://docs.open.cx/mcp/prompts

Copy any prompt below and paste it into your AI client. Each one maps to one or more OpenCX MCP tools automatically — no special syntax needed.

Copy any prompt below and paste it into your AI client. Each one maps to one or more OpenCX MCP tools automatically — no special syntax needed.

<Tip>
  For multi-step scenarios that chain several prompts together, see [Workflows](/mcp/use-cases).
</Tip>

## Inbox and Sessions

<AccordionGroup>
  <Accordion title="Browse and filter" icon="inbox">
    * *"List my open chat sessions"*
    * *"Show sessions from the last 7 days that were handed off"*
    * *"Filter sessions by the Billing team with negative sentiment"*
    * *"Find sessions tagged 'urgent' from the web channel"*
  </Accordion>

  <Accordion title="Investigate" icon="magnifying-glass">
    * *"Investigate ticket #4521 — why did the AI hand off?"*
    * *"Show me the full message history for session `<id>`"*
    * *"Show debug data for that session, including AI reasoning and citations"*
    * *"What handoff events happened in this session?"*
  </Accordion>

  <Accordion title="Take action" icon="paper-plane">
    * *"Resolve session `<id>`"*
    * *"Assign this session to @jane"*
    * *"Transfer this session to the Billing team"*
    * *"Add an internal comment: 'Checked — handoff was correct.'"*
    * *"Reply to the customer: 'Your refund has been processed.'"*
    * *"Tag this session as 'escalated'"*
  </Accordion>

  <Accordion title="Search" icon="search">
    * *"Search for messages mentioning 'refund policy'"*
    * *"Find contacts who asked about shipping"*
  </Accordion>
</AccordionGroup>

## Training

<AccordionGroup>
  <Accordion title="Browse and search" icon="brain">
    * *"List all training scenarios"*
    * *"Show draft training scenarios about returns"*
    * *"Search the knowledge base for 'cancellation policy'"*
    * *"Show the directory tree for training scenarios"*
  </Accordion>

  <Accordion title="Create and edit" icon="pen">
    * *"Create a draft training scenario titled 'Password reset flow' that walks the customer through resetting their password"*
    * *"Update the 'Refund process' scenario to mention the 30-day window"*
    * *"Move the 'Shipping FAQ' scenario into the 'Logistics' directory"*
    * *"Create a new training directory called 'Onboarding'"*
  </Accordion>

  <Accordion title="Publish and version" icon="rocket">
    * *"Publish the 'Password reset flow' training scenario"*
    * *"Unpublish the 'Old returns process' scenario"*
    * *"Show version history for the 'Refund process' scenario"*
    * *"Revert the 'Shipping FAQ' scenario to version 2"*
  </Accordion>

  <Accordion title="AI profile" icon="robot">
    * *"Show the current AI agent system prompt"*
    * *"Update the system prompt to mention our new return policy"*
  </Accordion>
</AccordionGroup>

## Phone Agents

<AccordionGroup>
  <Accordion title="Setup" icon="phone">
    * *"List available voices — I need a female US English voice"*
    * *"Create an inbound phone agent named 'Returns Hotline' with that voice"*
    * *"Show all phone agents"*
    * *"Get the full config for the 'Returns Hotline' agent"*
  </Accordion>

  <Accordion title="Knowledge and workflows" icon="book">
    * *"What knowledge sources are attached to the Returns Hotline agent?"*
    * *"Attach the 'Returns FAQ' knowledge source to the Returns Hotline agent"*
    * *"What workflows can the Returns Hotline agent trigger?"*
  </Accordion>

  <Accordion title="Calls" icon="phone-arrow-up-right">
    * *"Make an outbound call from the Returns Hotline agent to +1-555-000-1234"*
    * *"Delete the 'Test Agent' phone agent"*
  </Accordion>
</AccordionGroup>

## Analytics

<AccordionGroup>
  <Accordion title="CSAT" icon="star">
    * *"Show CSAT scores from the last 30 days"*
    * *"What's the CSAT score for session `<id>`?"*
  </Accordion>

  <Accordion title="Handoff and impact" icon="chart-line">
    * *"Show handoff analytics for the last 7 days — what are the top reasons?"*
    * *"Pull the impact report — what's our AI resolution rate?"*
  </Accordion>

  <Accordion title="SLA" icon="clock">
    * *"Show SLA compliance for this month"*
    * *"Break down SLA compliance by team"*
    * *"Show the SLA breach heatmap — when do most breaches happen?"*
    * *"What's the compliance trend over the last 4 weeks?"*
  </Accordion>

  <Accordion title="Customer insights" icon="lightbulb">
    * *"What customer insight categories do we have?"*
    * *"List recent customer insights"*
    * *"Show details for the top insight — which sessions does it reference?"*
    * *"Assign the billing insight to the Billing team"*
  </Accordion>
</AccordionGroup>

## Contacts and Teams

<AccordionGroup>
  <Accordion title="Contacts" icon="address-book">
    * *"List contacts"*
    * *"Create a contact: Jane Doe, [jane@example.com](mailto:jane@example.com), +1-555-000-1234"*
    * *"Update the contact with email [jane@example.com](mailto:jane@example.com) — set name to 'Jane Smith'"*
    * *"Delete the contact with ID `<id>`"*
  </Accordion>

  <Accordion title="Blocklist" icon="ban">
    * *"List blocked contacts"*
    * *"Block the contact [spam@example.com](mailto:spam@example.com)"*
    * *"Is the domain example.com blocked?"*
    * *"Unblock [user@example.com](mailto:user@example.com)"*
  </Accordion>

  <Accordion title="Teams and users" icon="users">
    * *"List all teams"*
    * *"Who are the available members on the Billing team?"*
    * *"Add @jane to the Billing team"*
    * *"List all users in the organization"*
  </Accordion>
</AccordionGroup>

## Workflows and Operations

<AccordionGroup>
  <Accordion title="Workflows" icon="diagram-project">
    * *"What workflow trigger types and action types are available?"*
    * *"List all workflows"*
    * *"Create an inactive workflow: on ticket-created, tag it as 'new' and notify Slack"*
    * *"Activate the 'New Ticket Tagger' workflow"*
    * *"Manually trigger the 'Weekly Report' workflow"*
    * *"Show runs for the 'New Ticket Tagger' workflow"*
  </Accordion>

  <Accordion title="AI actions" icon="bolt">
    * *"List all AI actions"*
    * *"Show the full payload spec for the 'Check order status' action"*
    * *"Create an action that calls our returns API"*
  </Accordion>

  <Accordion title="Outbound sequences" icon="paper-plane">
    * *"Create a 3-step outbound sequence: day 1 email, day 3 follow-up, day 7 final reminder"*
    * *"Start the 'Onboarding' sequence"*
    * *"Add contacts from the 'New Signups' list to the Onboarding sequence"*
  </Accordion>

  <Accordion title="Office hours and org" icon="clock">
    * *"Show the default office hours"*
    * *"Set default office hours to US Eastern, Monday through Friday 9am to 5pm"*
    * *"List custom office hours schedules"*
    * *"Create an office hours schedule for US Eastern, Monday through Friday 9am to 5pm"*
    * *"Show organization info"*
  </Accordion>
</AccordionGroup>

## Knowledge and Content

<AccordionGroup>
  <Accordion title="Website crawling" icon="spider-web">
    * *"List website datasources"*
    * *"Crawl [https://docs.example.com](https://docs.example.com) and add it as a knowledge source"*
    * *"Check the crawl status for the docs datasource"*
    * *"Re-crawl the docs datasource"*
  </Accordion>

  <Accordion title="Help center" icon="book">
    * *"List all help centers"*
    * *"Export the full content tree from our help center"*
    * *"List media files in the help center"*
  </Accordion>

  <Accordion title="Autopilot" icon="toggle-on">
    * *"What's the autopilot status for each channel?"*
    * *"Enable autopilot for the web channel"*
    * *"Disable autopilot for the email channel"*
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Workflows" icon="lightbulb" href="/mcp/use-cases">
    Multi-step scenarios that chain prompts together
  </Card>

  <Card title="Tools Reference" icon="toolbox" href="/mcp/tools">
    All available tools organized by domain
  </Card>

  <Card title="Get Started" icon="download" href="/mcp/install">
    Connect the MCP server to your AI client
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Tools Reference
Source: https://docs.open.cx/mcp/tools

Complete reference of every tool the OpenCX MCP server exposes, organized by domain.

The MCP server exposes over 140 tools across 25+ domains. Every tool listed here is available from any MCP-compatible client.

<Tip>
  Ask your AI assistant *"What OpenCX tools do you have?"* — it will enumerate all available tools live.
</Tip>

## Conversations

<AccordionGroup>
  <Accordion title="Chat Sessions" icon="messages">
    | Tool | Description |
    | - | - |
    | `list_sessions` | List sessions with filters (status, channel, date range) |
    | `filter_sessions` | Advanced search (sentiment, tags, teams, language) |
    | `get_session` | Get session details by ID |
    | `get_session_by_ticket` | Look up a session by ticket number |
    | `create_session` | Create a chat session for a contact |
    | `update_session` | Update session status (resolve, close, reopen) |
    | `assign_session` | Assign or unassign a session to an agent |
    | `transfer_session_to_team` | Transfer a session to a team |
    | `send_message` | Send a message in a session (as contact or agent) |
    | `add_session_comment` | Add an internal agent comment to a thread |
    | `get_session_history` | Get message history for a session |
    | `get_session_handoffs` | Get handoff event details for a session |
    | `get_session_tags` | Get all tags on a session |
    | `tag_session` | Add a tag to a session |
    | `untag_session` | Remove a tag from a session |
    | `set_session_sub_status` | Apply a custom status to a session (moves it to that status's built-in parent) |
    | `clear_session_sub_status` | Remove the custom status from a session, keeping its built-in status |
    | `investigate_session` | Deep investigation with summary and diagnostics |
    | `investigate_ticket` | Investigate a session by ticket number |
    | `investigate_session_debug` | Full debug data with AI reasoning and citations |
  </Accordion>

  <Accordion title="Contacts" icon="address-book">
    | Tool | Description |
    | - | - |
    | `list_contacts` | List contacts with cursor pagination |
    | `get_contact` | Retrieve one contact by ID, including its custom data |
    | `create_contact` | Create a contact (email, phone, name, custom data) |
    | `update_contact` | Update contact fields |
    | `delete_contact` | Delete a contact by ID |
  </Accordion>

  <Accordion title="Companies" icon="building">
    | Tool | Description |
    | - | - |
    | `list_companies` | List companies, newest first |
    | `search_companies` | Find companies by owner, attribute conditions (including before/after a date), or name, sorted and paged |
    | `get_company` | Retrieve one company with its attributes and owner |
    | `upsert_company` | Create or update a company by your external id |
    | `set_company_owner` | Set or clear the teammate who owns a company |
    | `list_contact_companies` | List the companies a contact belongs to |
    | `link_contact_to_company` | Add a company to a contact |
    | `link_contacts_to_companies` | Link up to 100 contacts to companies in one call |
    | `unlink_contact_from_company` | Remove one company from a contact |
  </Accordion>

  <Accordion title="Blocklist" icon="ban">
    | Tool | Description |
    | - | - |
    | `list_blocked_contacts` | List all blocked contacts |
    | `block_contact` | Block a contact by email |
    | `check_contact_blocked` | Check if a contact is blocked |
    | `unblock_contact` | Remove a contact from the blocklist |
    | `list_blocked_domains` | List all blocked email domains |
    | `block_domains` | Block one or more email domains |
    | `check_domain_blocked` | Check if a domain or email is blocked |
    | `unblock_domain` | Remove a domain from the blocklist |
    | `list_blocked_ips` | List all blocked IP addresses and CIDR ranges |
    | `block_ips` | Block one or more IP addresses or CIDR ranges |
    | `check_ip_blocked` | Check if an IP is blocked (including via a CIDR range) |
    | `unblock_ip` | Remove an IP from the blocklist |
  </Accordion>

  <Accordion title="Tags" icon="tags">
    | Tool | Description |
    | - | - |
    | `list_tags` | List or search tags (optional `search`, `category_id`, `limit`) |
    | `list_tags_in_use` | List tags currently applied to sessions |
    | `upsert_tag` | Create or update a tag |
    | `delete_tag` | Remove a tag |
    | `list_tag_categories` | List or search tag categories (optional `search`, `limit`) |
    | `create_tag_category` | Create a tag category |
    | `update_tag_category` | Update a tag category name or description |
    | `delete_tag_category` | Delete a tag category (tags become uncategorized) |
    | `get_auto_tagging_status` | Check if AI auto-tagging is enabled |
    | `set_auto_tagging` | Enable or disable AI auto-tagging |
  </Accordion>

  <Accordion title="Custom Statuses" icon="circle-half-stroke">
    | Tool | Description |
    | - | - |
    | `list_custom_statuses` | List the custom session statuses defined for the organization |
    | `get_custom_status` | Get one custom status by id |
    | `create_custom_status` | Define a custom status under a built-in one (open / closed\_resolved / closed\_unresolved) |
    | `update_custom_status` | Change a custom status's name, parent, customer-facing fields, or the teams allowed to set it |
    | `delete_custom_status` | Remove a custom status (sessions keep their built-in status) |
  </Accordion>

  <Accordion title="Search" icon="magnifying-glass">
    | Tool | Description |
    | - | - |
    | `search` | Full-text search across contacts and messages |
    | `search_sessions` | Search contacts and messages by keyword |
  </Accordion>
</AccordionGroup>

## AI Configuration

<AccordionGroup>
  <Accordion title="Autopilot" icon="toggle-on">
    | Tool | Description |
    | - | - |
    | `get_autopilot_status` | Get autopilot enabled/disabled status per channel |
    | `set_autopilot` | Enable or disable autopilot for a channel |
  </Accordion>

  <Accordion title="AI Training" icon="brain">
    | Tool | Description |
    | - | - |
    | `list_training_scenarios` | List training scenarios with filters and pagination |
    | `get_training_scenario` | Get a scenario by ID |
    | `create_training_scenario` | Create a scenario (type, draft, channels, segments) |
    | `update_training_scenario` | Update a scenario with diff or direct mode |
    | `delete_training_scenario` | Delete a scenario |
    | `publish_training_scenario` | Publish a draft scenario |
    | `toggle_training_draft` | Unpublish a scenario (set to draft) |
    | `get_training_version_history` | Get publish history for a scenario |
    | `revert_training_version` | Revert a scenario to a previous version |
    | `move_training_to_directory` | Move a scenario into a directory |
    | `search_training_knowledge` | Semantic search across training and knowledge base |
    | `get_ai_profile` | Get the AI agent identity and system prompt |
    | `update_ai_profile` | Update the AI agent system prompt |
  </Accordion>

  <Accordion title="Training Directories" icon="folder-tree">
    | Tool | Description |
    | - | - |
    | `list_training_directories` | List all directories |
    | `get_training_directory_tree` | Get full directory tree with items |
    | `create_training_directory` | Create a new directory |
    | `update_training_directory` | Rename a directory |
    | `delete_training_directory` | Delete a directory and its contents |
  </Accordion>

  <Accordion title="AI Actions" icon="bolt">
    | Tool | Description |
    | - | - |
    | `list_actions` | List all actions the AI agent can call |
    | `get_action` | Get an action with its full payload spec |
    | `create_action` | Create an action with parameters and request body |
    | `update_action` | Update an existing action |
    | `delete_action` | Delete a single action |
    | `list_action_tags` | List all unique tags across actions |
  </Accordion>
</AccordionGroup>

## Knowledge

<AccordionGroup>
  <Accordion title="Website Crawling" icon="spider-web">
    | Tool | Description |
    | - | - |
    | `list_datasources` | List website datasources |
    | `create_datasource` | Create a datasource and start crawling |
    | `get_datasource` | Get datasource details and crawl status |
    | `start_crawl` | Re-crawl an existing datasource |
    | `get_crawl_status` | Get progress of a crawl job |
    | `list_crawled_pages` | List discovered pages with filters |
  </Accordion>

  <Accordion title="Help Center" icon="book">
    | Tool | Description |
    | - | - |
    | `list_help_centers` | List all help centers |
    | `get_help_center` | Read a help center's settings, branding and custom code |
    | `update_help_center` | Change name, domain, CSS, head scripts or localizations |
    | `update_help_center_languages` | Change which languages are served |
    | `list_help_center_translation_jobs` | See which translations are still running |
    | `list_help_center_glossary_terms` | List terms the translator keeps as written |
    | `create_help_center_glossary_term` | Protect a term from being translated |
    | `import_help_center_glossary_terms` | Copy the organization glossary in one call |
    | `update_help_center_glossary_term` | Change a term or its definition |
    | `delete_help_center_glossary_term` | Remove a glossary term |
    | `list_help_center_topics` | List the topics in a help center |
    | `get_help_center_topic` | Read one topic and its names per language |
    | `create_help_center_topic` | Create a topic, at the top level or inside another |
    | `update_help_center_topic` | Rename, re-describe or re-icon a topic, per language |
    | `delete_help_center_topic` | Delete a topic, with or without its contents |
    | `restore_help_center_topic` | Bring a deleted topic back |
    | `retranslate_help_center_topic` | Translate a topic again, one language or all |
    | `list_help_center_articles` | List the articles in a help center |
    | `get_help_center_article` | Read one article and its versions |
    | `list_help_center_article_versions` | List an article's saved versions |
    | `list_help_center_article_backlinks` | The other articles that link to one, live per language and in drafts |
    | `get_help_center_article_language_states` | What is live and what is waiting, per language |
    | `create_help_center_article` | Create an article in a topic |
    | `update_help_center_article` | Replace an article's content with a new version |
    | `delete_help_center_article` | Delete an article |
    | `restore_help_center_article` | Bring a deleted article back |
    | `publish_help_center_article` | Publish an article, one language or all |
    | `unpublish_help_center_article` | Take an article off the live site |
    | `retranslate_help_center_article` | Translate an article again, one language or all |
    | `get_help_center_tree` | The whole tree for one language, in reading order |
    | `move_help_center_article` | Put an article in a topic, at a position |
    | `move_help_center_topic` | Nest a topic or lift it to the top level |
    | `reorder_help_center_tree` | Order one topic's children |
    | `list_help_center_media` | List media files in a help center |
    | `delete_help_center_media` | Delete a media file |
  </Accordion>
</AccordionGroup>

## Channels

<AccordionGroup>
  <Accordion title="Email" icon="envelope">
    | Tool | Description |
    | - | - |
    | `send_email` | Send AI-generated emails to contacts |
    | `list_email_domains` | List configured sending domains and their saved regions, when available |
    | `add_email_domain` | Add a custom sending domain with optional `region`: `eu-west-1` (default) or `us-east-1`. The region cannot be changed after creation. |
    | `verify_email_domain` | Verify a domain's DNS records |
  </Accordion>

  <Accordion title="AI Phone Agents" icon="phone">
    | Tool | Description |
    | - | - |
    | `list_voices` | List available voices (accent, gender, preview). A base language such as `ar` includes its regional voices |
    | `list_phone_agents` | List all phone agents |
    | `get_phone_agent` | Get a phone agent's full configuration |
    | `create_phone_agent` | Create a phone agent (voice, instructions, type) |
    | `update_phone_agent` | Update agent settings |
    | `delete_phone_agent` | Delete a phone agent and release its number |
    | `make_outbound_call` | Call a contact or number via an AI agent |
    | `present_phone_agent` | Re-display a phone agent's test card |
    | `get_phone_agent_knowledge_sources` | Get the instructions and knowledge an agent can use, and whether it loads or searches them |
    | `update_phone_agent_knowledge_sources` | Select the instructions and knowledge an agent can use; nothing selected means only its own instructions |
    | `get_phone_agent_workflows` | List workflows available to an agent |
    | `update_phone_agent_workflows` | Set workflows an agent can trigger |
  </Accordion>

  <Accordion title="WhatsApp" icon="comment">
    | Tool | Description |
    | - | - |
    | `send_whatsapp_template` | Send a WhatsApp template message |
  </Accordion>

  <Accordion title="Widget" icon="browser">
    | Tool | Description |
    | - | - |
    | `authenticate_widget_user` | Generate a JWT for an authenticated widget user |
  </Accordion>
</AccordionGroup>

## Operations

<AccordionGroup>
  <Accordion title="Teams" icon="users">
    | Tool | Description |
    | - | - |
    | `list_teams` | List all teams |
    | `get_team` | Get team details |
    | `create_team` | Create a team with optional support, office hours, assignment, category, and call settings |
    | `update_team` | Update a team |
    | `update_team_settings` | Change support, office hours, assignment strategy and pacing, category, and call settings |
    | `list_team_categories` | List categories in the current workspace |
    | `create_team_category` | Create a category or reuse an existing name |
    | `delete_team` | Delete a team |
    | `list_team_members` | List users in a team |
    | `list_available_team_members` | List available members with capacity |
    | `add_team_member` | Add a user to a team |
    | `remove_team_member` | Remove a user from a team |

    Use `list_team_categories` or `create_team_category` to find a category ID, then set `category_id` with `update_team_settings`. Send `null` to clear it. Categories organize teams without changing their routing. Category reads require `teams:read`; creation requires `teams:write`.

    Use `list_office_hours` to find a schedule, then set `support_office_hours_id`; `null` restores the workspace default. Schedules and categories must belong to the current workspace. Set `support_assignment_strategy` and `auto_assign_interval_seconds` to configure assignment. Pacing accepts `0` to turn it off or whole seconds from `15` to `3600`.

    To configure call routing, first use `get_team` to review the current settings,
    then call `update_team_settings` with the team ID and only the settings to change.
    This requires both `teams:read` and `teams:write`. Omitted settings stay unchanged;
    it does not add members, change their availability, or set organization-wide auto-answer.

    ```json theme={"dark"}
    {
      "team_id": "0bf22121-730a-4ba4-a481-5d13fbc7b312",
      "is_support_enabled": true,
      "telephony_pacing_enabled": true,
      "telephony_ring_seconds": 20,
      "telephony_queue_wait_seconds": 300,
      "telephony_distribution": "longest_available",
      "call_wrap_up_seconds": 60
    }
    ```

    Ring timeout accepts 10–120 seconds; maximum wait accepts 30–3,600 seconds.
    Wrap-up accepts 0–3,600 seconds: `0` disables it and `null` inherits the organization
    setting. Distribution accepts `longest_available` or `fewest_answered_today`.
    Enabling Support does not make an unstaffed or unavailable team ready to answer calls.
    See [inbound calls](/phone/inbound-calls) for routing prerequisites.
  </Accordion>

  <Accordion title="Users" icon="user">
    | Tool | Description |
    | - | - |
    | `list_org_users` | List organization users (search by name or email) |
    | `get_org_user` | Get a user with team memberships and availability |
  </Accordion>

  <Accordion title="Office Hours" icon="clock">
    | Tool | Description |
    | - | - |
    | `get_default_office_hours` | Get the org-wide default schedule |
    | `update_default_office_hours` | Set or replace the org-wide default schedule |
    | `list_office_hours` | List all custom schedules |
    | `get_office_hours` | Get a custom schedule with its shifts |
    | `create_office_hours` | Create a custom schedule with timezone and shifts |
    | `update_office_hours` | Update a custom schedule (replaces all shifts) |
    | `delete_office_hours` | Delete a custom schedule |
  </Accordion>

  <Accordion title="Organization" icon="building">
    | Tool | Description |
    | - | - |
    | `get_organization` | Get organization info |
    | `update_organization` | Update organization name |
  </Accordion>

  <Accordion title="Macros" icon="reply">
    | Tool | Description |
    | - | - |
    | `list_macros` | List all macros (saved replies) |
    | `get_macro` | Get a macro by ID |
    | `create_macro` | Create an org-wide macro (supports `{{variable}}` placeholders and up to 3 tappable options) |
    | `update_macro` | Update an org-wide macro, including its options |
    | `delete_macro` | Delete a macro |
    | `list_macro_variables` | List system + custom variables usable in macros (read-only) |

    Custom variables are authored in the OpenCX dashboard (**Settings → Macros → Variables**); the API and MCP surface them read-only via `list_macro_variables`. Macro attachments are also authored in the dashboard and returned read-only by `list_macros` and `get_macro`. Options can be set with `create_macro` and `update_macro`: `update_macro` takes the full list, so keep an option by passing its `id` and leave one out to remove it.
  </Accordion>

  <Accordion title="Outbound Sequences" icon="paper-plane">
    | Tool | Description |
    | - | - |
    | `create_sequence` | Create a sequence shell (name, brief, settings) |
    | `get_sequence` | Get a sequence, its steps and effective settings |
    | `update_sequence` | Update a sequence's name, brief, criteria, settings or reply instructions |
    | `set_sequence_steps` | Write the full step list of a draft sequence |
    | `edit_sequence_steps` | Surgically update, append or remove steps on any sequence |
    | `list_sequence_data_keys` | List the attached-data keys a sequence's people carry, with coverage |
    | `set_sequence_columns` | Choose the People-table columns |
    | `add_sequence_contacts` | Enroll people, with optional attached data |
    | `launch_sequence` | Launch a draft sequence |
    | `pause_sequence` | Pause a running sequence |
    | `resume_sequence` | Resume a paused sequence |
  </Accordion>

  <Accordion title="Workflows" icon="diagram-project">
    | Tool | Description |
    | - | - |
    | `list_workflow_definitions` | List available action types and their schemas |
    | `validate_workflow` | Validate workflow blocks without creating |
    | `create_workflow` | Create a workflow (saved as inactive draft) |
    | `list_workflows` | List all workflows with status |
    | `get_workflow` | Get a workflow with blocks and configuration |
    | `update_workflow` | Update a workflow draft |
    | `delete_workflow` | Delete a workflow and all versions |
    | `activate_workflow` | Activate the latest version |
    | `deactivate_workflow` | Deactivate the active version |
    | `trigger_workflow` | Manually trigger a workflow |
    | `list_workflow_runs` | List runs with status and cause filters |
    | `get_workflow_run` | Get a specific run with details |
  </Accordion>
</AccordionGroup>

## Analytics

<AccordionGroup>
  <Accordion title="CSAT" icon="star">
    | Tool | Description |
    | - | - |
    | `list_csat_scores` | List customer satisfaction scores |
    | `get_csat_score` | Get a specific CSAT score |
    | `get_session_csat` | Get the CSAT score for a session |
  </Accordion>

  <Accordion title="Handoff Analytics" icon="arrow-right-arrow-left">
    | Tool | Description |
    | - | - |
    | `get_handoff_analytics` | Handoff reasons, sentiment, trends, and resources |
    | `list_handoff_events` | List individual handoff events with explanations, filterable by reason |
  </Accordion>

  <Accordion title="SLA Policies" icon="file-contract">
    | Tool | Description |
    | - | - |
    | `list_sla_policies` | List all SLA policies |
    | `get_sla_policy` | Get a policy by ID |
    | `create_sla_policy` | Create a policy with target times |
    | `update_sla_policy` | Update a policy |
    | `delete_sla_policy` | Delete a policy |
  </Accordion>

  <Accordion title="SLA Analytics" icon="chart-bar">
    | Tool | Description |
    | - | - |
    | `get_sla_analytics_overview` | Compliance rates and time percentiles for a range |
    | `get_sla_analytics_breakdown` | Compliance grouped by policy, team, agent, or channel |
    | `get_sla_analytics_trend` | Compliance over time (daily or weekly) |
    | `get_sla_breach_heatmap` | Breach frequency by hour and day of week |
  </Accordion>

  <Accordion title="Impact Report" icon="chart-pie">
    | Tool | Description |
    | - | - |
    | `get_impact_report` | AI automation rate and resolution breakdown |
  </Accordion>

  <Accordion title="Customer Insights" icon="lightbulb">
    | Tool | Description |
    | - | - |
    | `list_insights` | List customer insights with pagination |
    | `get_insight` | Get a specific insight (includes archive policy and resurface progress) |
    | `resolve_insight` | Mark an insight as resolved |
    | `archive_insight` | Archive with resurface policy (`until_escalating`, `until_count`, `forever`) |
    | `unarchive_insight` | Remove archive state |
    | `assign_insight` | Assign an insight to a team |
    | `list_insight_categories` | List insight categories |
  </Accordion>
</AccordionGroup>

## Compliance and Audit

<AccordionGroup>
  <Accordion title="Audit Logs" icon="clipboard-list">
    | Tool | Description |
    | - | - |
    | `get_audit_logs` | Query change history and teammate sign-ins and sign-outs (who did what, when) |
  </Accordion>

  <Accordion title="Redaction" icon="eraser">
    | Tool | Description |
    | - | - |
    | `redact_message` | Redact a specific message by ID |
    | `redact_session` | Redact all messages in a session |
  </Accordion>

  <Accordion title="Media" icon="image">
    | Tool | Description |
    | - | - |
    | `upload_image` | Upload an image file and get an embeddable URL |
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Prompt Library" icon="message" href="/mcp/prompts">
    Ready-to-use prompts by domain
  </Card>

  <Card title="Workflows" icon="lightbulb" href="/mcp/use-cases">
    Multi-step scenarios that chain prompts together
  </Card>

  <Card title="Get Started" icon="download" href="/mcp/install">
    Connect the MCP server to your AI client
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Common issues and how to resolve them
  </Card>
</CardGroup>

## Contact segment management

Use `create_contact_segment`, `update_contact_segment`, and `delete_contact_segment` to manage saved contact filters. These tools require `segments:write`. Companion makes them available to users with contact write permission.

Updates change only supplied fields; supplying a definition replaces the complete filter rules. Membership recalculates in the background after creation or filter changes. Deletion removes the segment and its memberships while keeping contacts, and does not rewrite references in other configurations.

Use `list_contact_segments`, `get_contact_segment`, `list_segments_for_contact`, and `check_contact_in_segment` to inspect definitions and membership with `segments:read`. See [contact segments](/api-reference/contacts/segments/introduction) for examples.


# Mcp troubleshooting
Source: https://docs.open.cx/mcp/troubleshooting

Fix common MCP server issues — startup failures, missing tools, authentication errors, and empty responses.

Before debugging, confirm your API key is valid and Node.js 18+ is in your PATH.

<Tip>New to MCP? Start with the [Get Started](/mcp/install) guide.</Tip>

## Common Scenarios

| Symptom | Likely cause | Fix |
| - | - | - |
| **Server crashes on startup with "OPENCX\_API\_KEY is required"** | API key not set in your client config | Add `OPENCX_API_KEY` to the `env` block (or your client's equivalent). See [Get Started](/mcp/install) for the exact JSON. |
| **Tools not listed, never run, or Claude Code reports "MCP server not found"** | Malformed JSON, editor not restarted, wrong mode, missing env on PATH, or stale `npx` cache | Re-paste config from [Get Started](/mcp/install), fully restart the app, and run `npx -y @opencx/mcp` in a terminal to verify the package runs. Use [Cursor](/mcp/clients/cursor) (Agent mode), [Claude Desktop](/mcp/clients/claude-desktop) (full quit), [Claude Code](/mcp/clients/claude-code) (shell `OPENCX_API_KEY`), [VS Code](/mcp/clients/vscode), [Windsurf](/mcp/clients/windsurf), or [Zed](/mcp/clients/zed) for client-specific steps. |
| **Every tool call returns 401 or 403** | Invalid or revoked key, wrong org, or insufficient access for the operation | Create a new key under **Settings > API Keys** in your [OpenCX dashboard](https://platform.open.cx/settings/access) and update the config. |
| **Tool call succeeds but the payload is empty** | No matching data in the org (e.g. no sessions yet) | Confirm in the [inbox](https://platform.open.cx/inbox) or contacts, then retry with a known-good id. |
| **Remote endpoint (`api.open.cx/mcp`) returns 401 on connect** | Missing or malformed `Authorization` header | Send `Authorization: Bearer <api-key>` on the connection — see [Remote server](/mcp/install#remote-server-no-install) for per-client config. |
| **Sign-in connection returns 403 after it worked** | Your role was narrowed, or you were removed from the organization | Permissions are re-checked on every call. Ask an admin to restore the access you need, then retry — no reconnection is required. |
| **Sign-in connection points at the wrong organization** | A connection is bound to the organization picked when it was approved | Disconnect it under **Settings > API Keys > Connected apps**, add the server again, and choose the right organization on the consent screen. |
| **Your client never opens a browser to sign in** | The client is configured with an `Authorization` header, so it never starts the sign-in | Remove the header from the server entry and reconnect — see [Connect with your OpenCX sign-in](/mcp/install#connect-with-your-opencx-sign-in). |
| **Remote endpoint returns 405 on GET** | Expected — the hosted endpoint is stateless and offers no server-push SSE stream | Nothing to fix; MCP clients fall back to regular request/response automatically. |
| **None of the above** | — | Contact support at **[support@open.cx](mailto:support@open.cx)** with your error message and client name. |

<Info>
  Every tool call is logged in your OpenCX dashboard — check **Settings > Audit
  Logs** to see whether the call reached the API.
</Info>

***

## Related Documentation

<CardGroup>
  <Card title="Get Started" icon="download" href="/mcp/install">
    Re-check config JSON and setup steps
  </Card>

  <Card title="Cursor" icon="text-slash" href="/mcp/clients/cursor">
    Agent mode and MCP panel
  </Card>

  <Card title="VS Code" icon="code" href="/mcp/clients/vscode">
    mcp.json and Copilot Chat
  </Card>

  <Card title="Windsurf" icon="water" href="/mcp/clients/windsurf">
    mcp\_config.json and Cascade
  </Card>
</CardGroup>


# Workflows
Source: https://docs.open.cx/mcp/use-cases

Realistic multi-step workflows you can run from Claude Desktop, Cursor, or VS Code using the OpenCX MCP server.

These workflows show what the MCP server handles well in practice. Each one is a series of prompts you can type directly into your AI client.

## Investigate a Support Ticket

A customer escalated a ticket. Pull the full investigation into your editor instead of switching to the dashboard.

<Steps>
  <Step title="Look up the ticket">
    *"Investigate ticket #4521 — why did the AI hand off?"*
  </Step>

  <Step title="Read the AI's reasoning">
    *"Show me the debug data for that session, including the AI's reasoning steps and citations."*
  </Step>

  <Step title="Add an internal note">
    *"Add a comment on the last message: 'Checked — handoff was correct, agent lacked refund policy training.'"*
  </Step>
</Steps>

The assistant fetches the session summary, diagnostics, and handoff details, then posts a comment visible only to your team.

## Train Your Agent From Unresolved Sessions

Your AI agent handed off 30 sessions last week. Find the patterns and create training so it handles those topics next time.

<Steps>
  <Step title="Find unresolved sessions">
    *"List sessions from the last 7 days that were closed as unresolved."*
  </Step>

  <Step title="Analyze handoff reasons">
    *"Show me handoff analytics for the last 7 days — what are the top reasons?"*
  </Step>

  <Step title="Create training">
    *"Create a draft training scenario titled 'Subscription cancellation flow' that instructs the AI to walk the customer through cancellation steps and offer a retention discount before confirming."*
  </Step>

  <Step title="Review and publish">
    Review the draft in your [OpenCX dashboard](https://platform.open.cx), then:

    *"Publish the training scenario 'Subscription cancellation flow'."*
  </Step>
</Steps>

## Pull Insights for a Sprint Review

Your product team meets weekly. Get a summary of what customers asked about most, grouped by theme.

<Steps>
  <Step title="List insight categories">
    *"What customer insight categories do we have?"*
  </Step>

  <Step title="Fetch recent insights">
    *"List customer insights — show me the most recent ones with their categories and session counts."*
  </Step>

  <Step title="Drill into a theme">
    *"Show me the details for the top insight — which sessions does it reference?"*
  </Step>

  <Step title="Assign follow-ups">
    *"Assign the billing-related insight to the Billing team."*
  </Step>
</Steps>

## Set Up a New Phone Agent

Create an AI phone agent, attach knowledge, and make a test call — all from your editor.

<Steps>
  <Step title="Browse available voices">
    *"List available voices — I need a female US English voice."*
  </Step>

  <Step title="Create the agent">
    *"Create a phone agent named 'Returns Hotline' with that voice. Instructions: greet the caller, ask for their order number, then look up the return status."*
  </Step>

  <Step title="Attach knowledge sources">
    *"Attach the 'Returns FAQ' knowledge source to the Returns Hotline agent."*
  </Step>

  <Step title="Make a test call">
    *"Make an outbound call from the Returns Hotline agent to +1-555-000-1234."*
  </Step>
</Steps>

***

## Related Documentation

<CardGroup>
  <Card title="Prompt Library" icon="message" href="/mcp/prompts">
    Quick single-shot prompts by domain
  </Card>

  <Card title="Tools Reference" icon="toolbox" href="/mcp/tools">
    Full list of available tools by domain
  </Card>

  <Card title="Get Started" icon="download" href="/mcp/install">
    Connect the MCP server to your AI client
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Common issues and fixes
  </Card>
</CardGroup>


# Organization creation and environments
Source: https://docs.open.cx/organizations

Create an additional organization or fork an environment, understand admin access and billing ownership, and find the right path when you have no organizations.

## Create an organization

You must be an **Admin** in the organization you are creating from. General settings write access alone does not permit organization creation.

1. Open the organization switcher and select **Create organization**.
2. Enter a name in the dialog.
3. Review the billing organization shown by name and the final eight characters of its ID.
4. Select **Create**. OpenCX switches you to the new organization, where you are its initial Admin.

The source organization must still match your current organization when you open the dialog and submit it, including for OpenCX staff. If you see a message that they do not match, close the dialog, select the intended organization, and open the dialog again.

For customer accounts, **Bill to main Organization** is on and cannot be changed. The new organization records the same billing owner as the source organization. If the source has no separate billing owner, the source itself becomes the billing owner. This relationship does not grant parent members access to the new organization.

<Note>
  Billing ownership is recorded during creation. Recording this relationship does not itself change usage processing, subscriptions, or invoicing.
</Note>

For OpenCX staff, **Bill to main Organization** is off by default. Staff can turn it on to inherit the source organization's billing owner. Only staff can create standalone organizations, including from the organization selector. Standalone organizations record themselves as their billing owner. Staff can also create organizations without the source-org Admin role.

## Billing page

**Settings → Billing** currently shows “Billing portal coming soon 😉”. Plan details,
usage estimates, payment management, and subscription status are unavailable on this page.
The dashboard no longer displays overdue-payment banners. Existing subscriptions are unchanged.

## Create and manage environments

In **General settings → Environments**, choose **Create Environment** to fork the current organization. Creating, resetting, and syncing an environment's knowledge base requires Admin access in the source organization, with an exception for OpenCX staff. General settings read access continues to permit listing environments.

Forks copy source members and roles and always inherit the source's billing owner. Billing inheritance cannot be disabled for a fork, including by staff. Resetting an existing fork does not change its recorded billing owner.

These billing assignments apply to new organizations and forks. Existing billing ownership is unchanged.

## Partner and demo organizations

The [Partner API](/partners/api-reference) continues to create customer organizations using partner credentials. Each new customer organization records the partner's own organization as its billing owner. If the partner has no organization linked, OpenCX creates one using the partner's name and reuses it for future requests.

Demo organization creation remains available through the demo flow. Each new demo organization records itself as its billing owner.

## No organizations available

Ask your organization admin to invite you. The organization selector does not offer standalone creation to customer accounts.

## Accepting an invitation

1. Open the link in the invitation email.
2. Sign in with the email address the invitation was sent to. If you don't have an account yet, signing in creates one.
3. Select **Accept invitation**. OpenCX adds you to the organization with the roles your admin chose and opens it. Select **Decline** instead if you don't want to join.

The link alone never signs you in. Anyone who gets hold of it still has to sign in as the invited address, so a forwarded or leaked link cannot be used by someone else. If you sign in with a different address, OpenCX shows which address the invitation belongs to. Invitations expire after 7 days; ask your admin to resend one if yours has expired.


# Partner Admin Console
Source: https://docs.open.cx/partners/admin-console

A single dashboard page that lists every customer org connected to your partner account, with health indicators and one-click access to manage any of them.

The Partner Admin Console is a dashboard page inside OpenCX that gives you a live view of every customer org connected to your partner account. You log in once, and from a single screen you can see which orgs are active, which need attention, and jump into any one of them without juggling separate accounts.

It's the day-to-day place to operate the orgs you've already created — see how each one is doing and jump in when something needs your attention.

## When to use it

<CardGroup>
  <Card title="Daily monitoring" icon="chart-pulse">
    Spot which customer orgs aren't seeing any sessions, haven't been trained, or are sitting empty for weeks.
  </Card>

  <Card title="Customer support" icon="headset">
    A merchant emails you with a question. Open their org in one click, look at their inbox, and reply on their behalf.
  </Card>

  <Card title="Onboarding triage" icon="clipboard-check">
    See at a glance which newly-created orgs still need to be set up properly.
  </Card>

  <Card title="Reporting and BI" icon="magnifying-glass-chart">
    Quick visual snapshot of how many orgs you've onboarded and how active they are without exporting CSVs.
  </Card>
</CardGroup>

## Getting access

The Admin Console only appears when **the org you are signed into has been linked to your partner account** as the partner admin org. This is a one-time setup that the OpenCX team performs during partner onboarding — once done, every member of that org sees a "Partner Admin" item in the sidebar.

<Note>
  Each partner has exactly one admin org. Existing OpenCX users who are members of that org get console access; you don't issue new credentials. To add or remove people, manage members of the admin org as you would any other team in OpenCX.
</Note>

If you don't see the Partner Admin link in the sidebar, ask your OpenCX contact to link an org as your admin org.

## What you see

Once you click **Partner Admin** in the sidebar, you land on a single screen with three sections:

### Connected Orgs count

A large headline number at the top showing the total customer orgs linked to your partner account. This counts every org you've ever provisioned that hasn't been deleted.

### Partner header

Your partner name, support email, and logo as configured in your [white-label branding](/partners/branding) — a quick sanity check that customer-facing branding looks right.

### Connected orgs table

The main content. Every customer org under your partner account, one row per org, with these columns:

| Column | What it tells you |
| - | - |
| **Organization** | Org name plus the reference ID you use for it in your own system, so you can match a row to your customer record at a glance |
| **Status** | A health badge — `Healthy`, `Setup incomplete`, `Inactive`, or `New` (see below) |
| **Users** | How many people from the customer's team are using the org |
| **Data** | How many knowledge sources the AI has access to — crawled pages, uploaded docs, and similar |
| **AI** | Whether the AI has been given any training or instructions yet |
| **Actions** | Whether the org has connected any external integrations the AI can take action through |
| **Sessions (30d / all)** | Conversations in the last 30 days, and lifetime conversation count |
| **Last active** | Time since the most recent conversation — `2 hours ago`, `3 days ago`, or `Never` |

### Status badges

The status column rolls all the signals into one verdict so you can scan a long list quickly:

* **New** — created in the last 7 days and hasn't had any conversations yet. Expected; just give it time.
* **Setup incomplete** — the AI has nothing to work with: no knowledge, no actions. Reach out to the customer or finish setting it up for them.
* **Inactive** — set up correctly but hasn't seen a conversation in the last 30 days. The widget might not be live on the customer's site, traffic might be low, or the customer may have churned.
* **Healthy** — set up and seeing recent traffic. Nothing to do.

## Working with the table

### Search

The search box filters by **org name** or by your reference ID for it. The list narrows as you type — no need to press Enter.

The footer shows `X matches of Y total` so you always know whether you're looking at a slice or the full list.

### Pagination

Choose `10`, `25`, `50`, or `100` rows per page in the bottom-left dropdown. Use the chevron buttons to step through pages or jump to first/last.

The pagination math reflects the current search filter — searching "Acme" with 5 matches shows `1–5 of 5`, even if your partner has 10,000 total orgs.

## Actions per row

Two buttons live at the right of every row:

### Open

Drops you straight into the customer's org. You'll land on their inbox, exactly as if you were a member of their team — from there you can reply to messages, edit the AI's instructions, look at reports, configure integrations, anything a regular dashboard user can do, scoped to that one org.

<Note>
  Opening an org gives you basic access. Anything that requires admin rights — managing teammates, deleting data — needs the customer's admin to grant you a role first.
</Note>

To return to the Partner Admin Console, switch back to your admin org using the org switcher at the top of the dashboard.

### Copy login link

Generates a one-time login URL for that customer org and copies it to your clipboard. You'll be asked for an email — that's the address that will be signed in when the link is opened.

Common uses:

* A customer asks for a magic link on a support call — paste the URL into the chat.
* You want to invite someone (e.g. the customer's CEO) to look at their inbox without going through a password setup flow.

<Warning>
  Login links can only be used once and expire after **15 minutes**. They sign the recipient into one specific org — only share with people you trust to act on the customer's behalf.
</Warning>

## Frequently asked

<AccordionGroup>
  <Accordion title="Why don't I see the Partner Admin link in my sidebar?">
    Either (a) the org you're currently signed into hasn't been linked as your partner admin org, or (b) your partner account is inactive. Ask your OpenCX contact to verify the link, or use the org switcher to make sure you're signed into the correct org.
  </Accordion>

  <Accordion title="Can I have more than one partner admin org?">
    No. Each partner has exactly one admin org. If you need multiple teams to manage your orgs, add them all as members of that single admin org.
  </Accordion>

  <Accordion title="Does opening a customer org consume one of their seats?">
    No. Partner admin access doesn't count against the customer's seat or billing — it's a separate access grant tied to your partner account.
  </Accordion>

  <Accordion title="What happens if I'm already a member of the customer org?">
    "Open" just switches your active org. Nothing is duplicated.
  </Accordion>

  <Accordion title="Can my customers see that I opened their org?">
    Yes — anything you do inside their org is visible to them in the usual activity views, attributed to your user. Use this responsibly.
  </Accordion>

  <Accordion title="Why does the count in the header sometimes differ from the table?">
    The header card shows total connected orgs across your whole partner account. The table footer shows the count of the **current search filter**. With no search active, both numbers match.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup>
  <Card title="Integration Guide" icon="map" href="/partners/integration-guide">
    How to provision the orgs that show up in the console.
  </Card>

  <Card title="Branding" icon="paintbrush" href="/partners/branding">
    Configure the partner branding that appears in the console header and across customer dashboards.
  </Card>

  <Card title="API Reference" icon="code" href="/partners/api-reference">
    Programmatic alternatives to the actions in the console.
  </Card>

  <Card title="Partner Program" icon="handshake" href="/partners/introduction">
    Overview of how the Partner Program works.
  </Card>
</CardGroup>


# Partner Analytics
Source: https://docs.open.cx/partners/analytics

Report across every customer org connected to your partner account — ask Companion for a cross-org dashboard, or query the partner-scoped analytics views directly.

Partner Analytics lets the **partner admin org** report across every customer org connected to the partner account — volume, automation rate, CSAT, handoff reasons, SLA — network-wide and per customer, and answer customer-health questions (who is inactive, who hasn't finished setup, who is new, which channels each customer uses) without opening each org one at a time.

It is available anywhere OpenCX analytics already run: **Companion** (ask a question or have it build a dashboard) and the **public API**.

## Who can use it

Only members of your **partner admin org** — the same org that has the [Partner Admin Console](/partners/admin-console) — with the reports permission. Every other org gets `403 Forbidden` from the partner analytics endpoints; a customer org can never read another customer's data.

The scope is exactly the console's *Connected Orgs* list: every org linked to your partner account that has not been deleted. A newly connected org appears on the next query; a removed one drops out.

## Ask Companion

Open Companion from your partner admin org and ask in plain language. Companion knows this org administers a partner and picks the right scope:

* "Which of our customers had the most sessions this month?"
* "What's the automation rate per connected org over the last 30 days?"
* "Which of our clients have the most handoffs, and why?"
* "Which customers are inactive, and who hasn't set up AI yet?"
* "Which clients have the most booking links shared?"
* "What are the top contact reasons across the network?"
* "Tell me about Sea Rocket — how are they doing?"
* "Build me a dashboard of session volume, resolution rate and CSAT across all connected orgs, with a filter on our `rank-1` tag."

Answers name your orgs (never raw ids). Ask for a **dashboard** and Companion builds a Mini App you can reopen and share from **Apps** — the same Mini Apps used for org-scoped reporting, now over the partner network.

<Frame>
  <img alt="Companion answering a partner-wide question: automation rate per connected org, named" />
</Frame>

<Frame>
  <img alt="A published partner network dashboard mini app: roll-up tiles, tag filter and a ranked per-org table" />
</Frame>

<Frame>
  <img alt="A partner mini app tracking AI booking-link sharing across connected orgs" />
</Frame>

<Frame>
  <img alt="Companion answering a customer question: repeat-customer rate and languages per client, named" />
</Frame>

<Frame>
  <img alt="Booking-link performance dashboard: ranked clients with a per-client weekly drill-down" />
</Frame>

<Note>
  Companion distinguishes "this org's own support desk" from "the partner network". If a question could mean either, it asks once rather than guessing.
</Note>

## Public API

Three endpoints, authenticated with an **org-level API key of the partner admin org** holding the `reports:read` scope (not a Partner API key).

### List connected orgs

`GET /partner-analytics/orgs` — the roster and the org dimension for every partner query.

```json theme={"dark"}
{
  "partner": { "id": "…", "name": "FareHarbor" },
  "data": [
    { "id": "…", "name": "Alpha Boats", "external_id": "alpha", "tags": ["rank-1"], "created_at": "2026-05-01T00:00:00.000Z" }
  ],
  "total": 1
}
```

`external_id` is the reference you supplied when provisioning the org; `tags` are your partner-private labels from the console.

### Search connected orgs with health signals

`GET /partner-analytics/orgs/search` — the customer directory the Partner Admin console shows, paginated (`limit` ≤ 100, `offset`; `total` is the filtered count). Filter with `q` (name or `external_id`), `status`, `tags`, `channels` (comma-separated — tags match any, channels match all), `has_ai` and `has_actions` (`true`/`false`); sort with `sort_by` (`created_at`, `name`, `members`, `data_sources`, `sessions_30d`, `total_sessions`, `last_session_at`) and `sort_dir`.

```json theme={"dark"}
{
  "partner": { "id": "…", "name": "FareHarbor" },
  "data": [
    {
      "id": "…", "name": "Alpha Boats", "external_id": "alpha", "website": null, "logo_url": null,
      "created_at": "2026-05-01T00:00:00.000Z", "tags": ["rank-1"],
      "health": {
        "status": "healthy", "members": 3, "data_sources": 12, "has_ai_training": true, "has_actions": true,
        "sessions_30d": 418, "total_sessions": 5120, "last_session_at": "2026-08-17T09:12:44.000Z"
      },
      "channels": { "chat": true, "email": true, "whatsapp": false, "voice": false }
    }
  ],
  "total": 1, "limit": 50, "offset": 0
}
```

`health.status` is `new` (connected less than 7 days ago, no sessions yet), `setup_incomplete` (no knowledge sources and no actions), `inactive` (no session in the last 30 days) or `healthy`.

### Run a partner-wide analytics query

`POST /partner-analytics/query` — a single read-only `SELECT` over the partner-scoped analytics views. Same request and response contract as the org-scoped `POST /reports/analytics`.

```json theme={"dark"}
{
  "sql": "SELECT org_id, count() AS sessions, round(100.0 * countIf(ai_status IN ('resolved','assumed_resolved')) / nullIf(count(), 0), 1) AS ai_resolved_pct FROM report_partner_sessions WHERE created_at >= now() - INTERVAL 30 DAY GROUP BY org_id ORDER BY sessions DESC",
  "parameters": []
}
```

The views are `report_partner_sessions`, `report_partner_messages`, `report_partner_session_metrics`, `report_partner_session_tags`, `report_partner_csat`, `report_partner_sla`, `report_partner_handoff_reason_categories`, `report_partner_handoff_reasons`, `report_partner_resource_usage`, `report_partner_contacts`, `report_partner_contact_reasons` and `report_partner_contact_reason_runs` — the same columns as the org `report_*` views, plus an **`org_id`** column. Join `org_id` to the roster above to name orgs. `report_partner_messages` includes the full message text, so link and keyword analysis ("booking links shared per customer") works network-wide, and the contact views cover your customers' end users and their contact reasons.

* Read-only, scoped server-side to your connected orgs; results are capped at 500 rows (`truncated: true` when more existed).
* The org `report_*` views are not reachable from this endpoint, and the `report_partner_*` views are not reachable from `/reports/analytics`.
* A query that runs past the time limit fails with `400`, and repeating the exact same query returns that error for about 15 seconds before it runs again. When an identical query is already running, a second request waits for its result; if it is still running after about a minute, the request returns `503` — retry shortly. Narrow the date range or simplify the query if it keeps timing out.

## Related

<CardGroup>
  <Card title="Partner Admin Console" icon="gauge" href="/partners/admin-console">
    The Connected Orgs list that defines the analytics scope.
  </Card>

  <Card title="Partner API Reference" icon="code" href="/partners/api-reference">
    Provisioning orgs, keys, and login links.
  </Card>
</CardGroup>


# API Reference
Source: https://docs.open.cx/partners/api-reference

All Partner API requests require a Bearer token in the Authorization header. Partner API keys are provisioned by the OpenCX team — they are separate from org-level API keys.

## Authentication

All Partner API requests require a **Bearer token** in the `Authorization` header. Partner API keys are provisioned by the OpenCX team — they are separate from org-level API keys.

```bash theme={"dark"}
Authorization: Bearer YOUR_PARTNER_API_KEY
```

**Base URL:** `https://api.open.cx`

### IP allow list

Partner API endpoints support **IP-level access control**. When an allow list is configured on your partner account, requests from IPs not in the list are rejected with `403 Forbidden` — even with a valid API key.

All traffic passes through Cloudflare, which forwards the real client IP in the `X-Forwarded-For` header. The backend extracts and validates this IP on every request.

<Note>
  IP allow lists are configured by the OpenCX team during onboarding. Contact us to add, update, or remove IPs. When no allow list is set, requests are accepted from any IP (token-only authentication).
</Note>

### Security layers

| Layer | What it does |
| - | - |
| **Bearer token** | Every request must include a valid partner API JWT. Revoked or missing keys return `401`. |
| **IP allow list** | When configured, only requests from whitelisted IPs are accepted. Others get `403`. |
| **Partner active check** | Inactive partner accounts are blocked at the auth layer (`401`). |
| **Rate limiting** | 100 req/min per partner globally, plus per-endpoint limits. |
| **Org ownership** | All org-scoped endpoints verify the org belongs to the calling partner (`403` otherwise). |

***

## Create Org

Create a new organization for one of your customers.

The authenticated partner's own organization is recorded as the new customer's billing owner. If the partner account has no organization linked, OpenCX provisions one using the partner's name, records it as its own billing owner, and links it to the partner account. Later requests reuse that organization, including simultaneous creation requests. The partner's own organization is separate from the customer orgs returned by **List Orgs**.

Billing ownership is assigned by OpenCX; callers cannot override it in the request. Existing customer orgs keep their current billing ownership. Recording ownership does not itself change usage processing, subscriptions, or invoicing.

When a partner organization is automatically provisioned, designated OpenCX staff accounts receive Admin access in that organization if those accounts already exist. Missing accounts are logged and skipped without interrupting provisioning. This does not add staff to customer organizations or change memberships in an existing partner organization.

```
POST /partner/v1/orgs
```

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Display name for the org. |
| `external_id` | string | No | Your internal ID for this customer. Must be unique per partner — duplicates return `409`. |
| `website` | string | No | Customer's website URL. |
| `language` | string | No | Default language code (e.g. `"en"`, `"es"`, `"de"`). Defaults to `"en"`. |
| `ai_instructions` | string | No | The AI profile — system prompt that defines the agent's personality, knowledge scope, and behavior. Overrides your partner-level default if set. |
| `integrations` | object | No | Auto-connect integrations during creation. See below. |

### Integrations

Pass credentials in the `integrations` object to auto-connect supported third-party integrations during org creation. Credentials are validated against the live third-party API — invalid credentials cause the request to fail with a `400`.

Each integration has its own shape under its own key. Some integrations accept either a **single object** (for one connection) or an **array** (for multiple connections — different locations, brands, or currencies). When passing an array, each entry should include a `name` that the AI uses in conversations to disambiguate between connections.

#### FareHarbor

Key: `fareharbor`

| Field | Type | Required | Description |
| - | - | - | - |
| `app_key` | string | Yes | FareHarbor API **App Key**. |
| `user_key` | string | Yes | FareHarbor API **User Key**. |
| `name` | string | No | Label for this connection, used by the AI to disambiguate between multiple connections. Defaults to `"Default"`. |
| `default_company_shortname` | string | No | The FareHarbor company shortname to use by default when the org has access to multiple companies. |

Single connection (object form):

```json theme={"dark"}
{
  "integrations": {
    "fareharbor": {
      "name": "Primary",
      "app_key": "...",
      "user_key": "...",
      "default_company_shortname": "acme-tours"
    }
  }
}
```

Multiple connections (array form):

```json theme={"dark"}
{
  "integrations": {
    "fareharbor": [
      { "name": "Account A", "app_key": "...", "user_key": "...", "default_company_shortname": "acme-tours" },
      { "name": "Account B", "app_key": "...", "user_key": "...", "default_company_shortname": "acme-adventures" }
    ]
  }
}
```

<Note>
  Supported integration keys and their per-integration field shapes are documented above. This section will expand as more integrations become available via the provisioning API. For integrations not yet supported here, use the org-level dashboard or API after creation.
</Note>

### Response

```json 201 Created theme={"dark"}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme Tours",
  "widget_token": "f8e7d6c5b4a39281...",
  "external_id": "customer-12345"
}
```

| Field | Type | Description |
| - | - | - |
| `id` | string | The org UUID. Use this to manage the org via other OpenCX APIs. |
| `name` | string | The org name as provided. |
| `widget_token` | string | Widget embed token. Pass this to the chat widget. |
| `external_id` | string \| null | Your external ID, echoed back. |

### Error responses

| Status | Condition | Body |
| - | - | - |
| `400` | Invalid request body, or integration credentials failed validation. | `{ "statusCode": 400, "message": "..." }` |
| `401` | Missing, invalid, or revoked API key. | `{ "statusCode": 401, "message": "..." }` |
| `409` | An org with this `external_id` already exists for your partner. | `{ "statusCode": 409, "message": "Org with external_id \"...\" already exists" }` |

### Examples

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.open.cx/partner/v1/orgs \
    -H "Authorization: Bearer YOUR_PARTNER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Acme Tours",
      "external_id": "customer-12345",
      "language": "en",
      "ai_instructions": "You are a support agent for Acme Tours. Help customers with bookings and questions."
    }'
  ```

  ```javascript Node.js theme={"dark"}
  const response = await fetch('https://api.open.cx/partner/v1/orgs', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_PARTNER_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Acme Tours',
      external_id: 'customer-12345',
      language: 'en',
      ai_instructions: 'You are a support agent for Acme Tours. Help customers with bookings and questions.',
    }),
  });

  const org = await response.json();
  ```

  ```python Python theme={"dark"}
  import requests

  response = requests.post(
      'https://api.open.cx/partner/v1/orgs',
      headers={'Authorization': 'Bearer YOUR_PARTNER_API_KEY'},
      json={
          'name': 'Acme Tours',
          'external_id': 'customer-12345',
          'language': 'en',
          'ai_instructions': 'You are a support agent for Acme Tours. Help customers with bookings and questions.',
      },
  )

  org = response.json()
  ```
</CodeGroup>

***

## List Orgs

List all organizations created by your partner account.

```
GET /partner/v1/orgs
```

### Query parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `limit` | number | 50 | Number of orgs to return (1–100). |
| `offset` | number | 0 | Number of orgs to skip (for pagination). |

### Response

```json 200 OK theme={"dark"}
{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Acme Tours",
      "widget_token": "f8e7d6c5b4a3...",
      "external_id": "customer-12345",
      "created_at": "2026-03-15T10:30:00.000Z"
    }
  ],
  "total": 142
}
```

### Examples

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl "https://api.open.cx/partner/v1/orgs?limit=10&offset=0" \
    -H "Authorization: Bearer YOUR_PARTNER_API_KEY"
  ```

  ```javascript Node.js theme={"dark"}
  const response = await fetch('https://api.open.cx/partner/v1/orgs?limit=10&offset=0', {
    headers: { 'Authorization': 'Bearer YOUR_PARTNER_API_KEY' },
  });

  const { data, total } = await response.json();
  ```

  ```python Python theme={"dark"}
  import requests

  response = requests.get(
      'https://api.open.cx/partner/v1/orgs',
      headers={'Authorization': 'Bearer YOUR_PARTNER_API_KEY'},
      params={'limit': 10, 'offset': 0},
  )

  result = response.json()
  ```
</CodeGroup>

***

## Get Org by external\_id

Look up a single org by the `external_id` you supplied at creation. Use this when you need to reverse-resolve from your internal identifier to the OpenCX org — for example, before creating an API key or generating a login link — without paginating through `/orgs`.

```
GET /partner/v1/orgs/by-external-id/:externalId
```

### Path parameters

| Parameter | Type | Description |
| - | - | - |
| `externalId` | string | The `external_id` you set when calling `POST /partner/v1/orgs`. URL-encode it if it contains reserved characters. |

### Response

```json 200 OK theme={"dark"}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme Tours",
  "widget_token": "f8e7d6c5b4a39281...",
  "external_id": "customer-12345",
  "created_at": "2026-03-15T10:30:00.000Z"
}
```

### Error responses

| Status | Condition |
| - | - |
| `401` | Invalid or revoked partner API key. |
| `404` | No org with this `external_id` exists for your partner account. |

<Note>
  Lookups are scoped to your partner account. If a different partner has an org with the same `external_id`, you will not see it — you only ever resolve orgs you created.
</Note>

### Examples

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl "https://api.open.cx/partner/v1/orgs/by-external-id/customer-12345" \
    -H "Authorization: Bearer YOUR_PARTNER_API_KEY"
  ```

  ```javascript Node.js theme={"dark"}
  const externalId = encodeURIComponent('customer-12345');
  const response = await fetch(`https://api.open.cx/partner/v1/orgs/by-external-id/${externalId}`, {
    headers: { 'Authorization': 'Bearer YOUR_PARTNER_API_KEY' },
  });

  if (response.status === 404) {
    // org with this external_id doesn't exist yet — create it
  }

  const org = await response.json();
  ```

  ```python Python theme={"dark"}
  import requests
  from urllib.parse import quote

  external_id = quote('customer-12345', safe='')
  response = requests.get(
      f'https://api.open.cx/partner/v1/orgs/by-external-id/{external_id}',
      headers={'Authorization': 'Bearer YOUR_PARTNER_API_KEY'},
  )

  if response.status_code == 404:
      # org with this external_id doesn't exist yet — create it
      pass

  org = response.json()
  ```
</CodeGroup>

***

## Create Org API Key

Create an API key for a specific org. The returned key authenticates requests to the [OpenCX Public API](/api-reference/authentication) (crawling, training, contacts, etc).

```
POST /partner/v1/orgs/:orgId/api-keys
```

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | A label for the key (e.g. `"Production"`). Defaults to `"Default"`. |

### Response

```json 201 Created theme={"dark"}
{
  "api_key_id": "key-uuid-here",
  "api_key": "eyJhbGciOi..."
}
```

| Field | Type | Description |
| - | - | - |
| `api_key_id` | string | The key's UUID. |
| `api_key` | string | The JWT API key. Use this as `Bearer` token for org-level API calls. |

<Warning>
  The full API key is only returned once — store it securely. If lost, create a new one.
</Warning>

### Examples

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.open.cx/partner/v1/orgs/ORG_ID/api-keys \
    -H "Authorization: Bearer YOUR_PARTNER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Production" }'
  ```

  ```javascript Node.js theme={"dark"}
  const response = await fetch(`https://api.open.cx/partner/v1/orgs/${orgId}/api-keys`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_PARTNER_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'Production' }),
  });

  const { api_key_id, api_key } = await response.json();
  ```

  ```python Python theme={"dark"}
  import requests

  response = requests.post(
      f'https://api.open.cx/partner/v1/orgs/{org_id}/api-keys',
      headers={'Authorization': 'Bearer YOUR_PARTNER_API_KEY'},
      json={'name': 'Production'},
  )

  result = response.json()
  api_key = result['api_key']
  ```
</CodeGroup>

### Error responses

| Status | Condition |
| - | - |
| `401` | Invalid or revoked partner API key. |
| `403` | Org does not belong to this partner. |

***

## Revoke Org API Key

Permanently delete an org API key. Once revoked, the key can no longer authenticate requests to the [OpenCX Public API](/api-reference/authentication).

```
DELETE /partner/v1/orgs/:orgId/api-keys/:apiKeyId
```

### Path parameters

| Parameter | Type | Description |
| - | - | - |
| `orgId` | string | The org that owns the key. Must belong to your partner account. |
| `apiKeyId` | string (uuid) | The `api_key_id` returned when the key was created. |

Revocation is org-scoped: any key under an org you own can be revoked, regardless of who created it (partner API or the org's own dashboard).

### Response

```json 200 OK theme={"dark"}
{
  "success": true
}
```

<Note>
  Revocation propagates to all API servers within **\~60 seconds**. Each server caches API keys in-process with a 60-second TTL, so a revoked key may continue to authenticate on some servers until that TTL lapses.
</Note>

### Examples

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X DELETE https://api.open.cx/partner/v1/orgs/ORG_ID/api-keys/API_KEY_ID \
    -H "Authorization: Bearer YOUR_PARTNER_API_KEY"
  ```

  ```javascript Node.js theme={"dark"}
  const response = await fetch(
    `https://api.open.cx/partner/v1/orgs/${orgId}/api-keys/${apiKeyId}`,
    {
      method: 'DELETE',
      headers: { 'Authorization': 'Bearer YOUR_PARTNER_API_KEY' },
    },
  );

  const { success } = await response.json();
  ```

  ```python Python theme={"dark"}
  import requests

  response = requests.delete(
      f'https://api.open.cx/partner/v1/orgs/{org_id}/api-keys/{api_key_id}',
      headers={'Authorization': 'Bearer YOUR_PARTNER_API_KEY'},
  )

  result = response.json()
  ```
</CodeGroup>

### Error responses

| Status | Condition |
| - | - |
| `400` | `apiKeyId` is not a valid uuid. |
| `401` | Invalid or revoked partner API key. |
| `403` | Org does not belong to this partner. |
| `404` | No API key with that id exists under the org. |

***

## Create Login Link

Generate a short-lived, single-use URL that logs a user directly into the dashboard with the correct org context. No email, no forms, no org picker — the user lands in the dashboard immediately.

Use this instead of invitations when you want **frictionless access** — for example, embedding a "Manage support" button in your own platform that takes the user straight into their dashboard.

```
POST /partner/v1/orgs/:orgId/login-links
```

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `email` | string | Yes | Email address of the user. If no account exists, one is created automatically. |
| `name` | string | No | Display name for the user (used only when creating a new account). Defaults to the email prefix. |
| `role_ids` | string\[] | No | Array of role UUIDs to assign when creating org membership. Ignored if user is already a member. |

### Response

```json 201 Created theme={"dark"}
{
  "url": "https://platform.open.cx/partner-login?token=a1b2c3...",
  "expires_at": "2026-04-12T12:15:00.000Z"
}
```

| Field | Type | Description |
| - | - | - |
| `url` | string | The login URL. Redirect the user's browser here. |
| `expires_at` | string | ISO 8601 timestamp. The link expires **15 minutes** after creation. |

<Warning>
  Login links are **single-use** — once a user visits the URL, it is consumed and cannot be reused. Generate a new link for each login session.
</Warning>

### Security properties

| Property | Value |
| - | - |
| Token entropy | 256 bits (cryptographically random) |
| TTL | 15 minutes |
| Single-use | Token deleted on first use |
| Rate limit | 30 links/min per partner |

### Error responses

| Status | Condition |
| - | - |
| `401` | Invalid or revoked partner API key. |
| `403` | Org does not belong to this partner. |

### Examples

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.open.cx/partner/v1/orgs/ORG_ID/login-links \
    -H "Authorization: Bearer YOUR_PARTNER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "email": "owner@acmetours.com", "name": "Jane Smith" }'
  ```

  ```javascript Node.js theme={"dark"}
  const response = await fetch(`https://api.open.cx/partner/v1/orgs/${orgId}/login-links`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_PARTNER_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: 'owner@acmetours.com',
      name: 'Jane Smith',
    }),
  });

  const { url, expires_at } = await response.json();
  // Redirect the user's browser to `url`
  ```

  ```python Python theme={"dark"}
  import requests

  response = requests.post(
      f'https://api.open.cx/partner/v1/orgs/{org_id}/login-links',
      headers={'Authorization': 'Bearer YOUR_PARTNER_API_KEY'},
      json={
          'email': 'owner@acmetours.com',
          'name': 'Jane Smith',
      },
  )

  result = response.json()
  login_url = result['url']
  # Redirect the user's browser to login_url
  ```
</CodeGroup>

***

## Idempotency

Use `external_id` to prevent duplicate orgs. If you call `POST /partner/v1/orgs` twice with the same `external_id`, the second call returns `409 Conflict`. This makes it safe to retry org creation without risk of duplicates. Use [`GET /partner/v1/orgs/by-external-id/:externalId`](#get-org-by-external_id) to resolve the existing org directly — no pagination required.

<Note>
  The `external_id` uniqueness constraint is scoped to your partner account. Different partners can use the same `external_id` values.
</Note>


# Branding
Source: https://docs.open.cx/partners/branding

When your customers log into the OpenCX dashboard through an org you created, they see your brand instead of OpenCX's default branding.

When your customers log into the OpenCX dashboard through an org you created, they see **your brand** instead of OpenCX's default branding.

## What's customizable

| Element | Where it appears | Field |
| - | - | - |
| **Logo** | Sidebar header, handoff insights (expert popover and recommendation modal) | `logo_url` |
| **App name** | Browser tab title (replaces "Open"), sidebar menu item ("\[name]'s agent"), chat page heading, handoff insights expert labels | `app_name` |
| **Support email** | All "contact us" links and error messages across the dashboard | `support_email` |
| **Primary color** | Reserved for future use (v2) | `primary_color` |

## How it works

Branding is configured on your **partner record** — not on individual orgs. Every org you create inherits your branding automatically.

```mermaid theme={"dark"}
graph LR
  Partner["partners table"] -->|"logo_url, app_name, support_email"| Org["chatbots row (partner_id)"]
  Org -->|"GET /copilot/current"| Dashboard["Dashboard UI"]
  Dashboard -->|"partner_branding != null"| BrandedUI["Your logo + name + email"]
```

## Configuration

Branding fields are set on your partner record during onboarding. Contact the OpenCX team to update them.

| Field | Type | Example |
| - | - | - |
| `logo_url` | URL to your logo image (SVG or PNG recommended, square aspect ratio) | `https://cdn.example.com/logo.svg` |
| `app_name` | Name shown in the browser tab | `"Booking Support"` |
| `support_email` | Email shown in all "contact us" copy | `"support@booking.com"` |
| `primary_color` | Hex color code (reserved for v2) | `"#003580"` |

<Note>
  Use a square logo (1:1 aspect ratio) for best results. The logo renders at 32x32px in the sidebar. SVG is preferred for crisp rendering at all sizes.
</Note>

## What's not branded (v1)

These elements currently show OpenCX defaults regardless of partner configuration:

* **Login page** — The auth page loads before any org context is available. Branding kicks in after login. Partners using [Login Links](/partners/api-reference#create-login-link) bypass this page entirely.
* **Invitation accept page** — Same constraint as login.
* **Favicon and Open Graph image** — Static assets that require per-domain serving.
* **Primary color theming** — Changing `--primary` also requires computing a contrast-safe `--primary-foreground`. Deferred to v2.

## Billing

For partner orgs, the **Billing** page is automatically hidden from the settings navigation and command palette. Partners handle billing with their customers directly — OpenCX bills the partner at the account level.


# Integration Guide
Source: https://docs.open.cx/partners/integration-guide

End-to-end guide to provisioning a fully trained, live AI support agent for your customers.

This guide walks through the complete lifecycle of setting up a customer org — from creation to a fully trained AI agent handling live conversations.

## Overview

```mermaid theme={"dark"}
graph LR
    A["1. Create org"] --> B["2. Create org API key"]
    B --> C["3. Crawl website"]
    C --> D["4. Add training"]
    D --> E["5. Grant dashboard access"]
    E --> G["6. Embed widget"]
    G --> F["Live"]
```

***

## Step 1: Create the org

Use your **Partner API key** to create an org for your customer.

```bash theme={"dark"}
curl -X POST https://api.open.cx/partner/v1/orgs \
  -H "Authorization: Bearer YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Tours",
    "external_id": "acme-123",
    "website": "https://acmetours.com",
    "language": "en",
    "ai_instructions": "You are a helpful support assistant for Acme Tours. Help customers with booking questions, cancellations, and tour information. Be friendly and concise."
  }'
```

Save the `id` and `widget_token` from the response — you'll need both.

<Note>
  The `ai_instructions` field is the AI profile — the system prompt that defines the agent's personality, knowledge scope, and behavior. Write it as if you're briefing a new support agent — who they work for, what they help with, and how they should behave.
</Note>

<Tip>
  See the full request/response schema in the [Create Org API Reference](/partners/api-reference#create-org).
</Tip>

***

## Step 2: Create an org API key

The Partner API creates the org, but to **train** the AI and **manage** the org, you need an **org-level API key**. Create one with your partner key:

```bash theme={"dark"}
curl -X POST https://api.open.cx/partner/v1/orgs/ORG_ID/api-keys \
  -H "Authorization: Bearer YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production" }'
```

Save the `api_key` from the response — this is the org-level API key you'll use for all subsequent calls.

<Warning>
  The org API key is different from your partner API key. The partner key manages orgs. The org key manages a specific org's data (training, crawling, contacts, etc). The key is only returned once — store it securely.
</Warning>

All subsequent API calls use the org key:

```bash theme={"dark"}
Authorization: Bearer ORG_API_KEY
```

<Tip>
  See the full request/response schema in the [Create Org API Key Reference](/partners/api-reference#create-org-api-key).
</Tip>

***

## Step 3: Crawl the customer's website

The fastest way to train the AI is to crawl the customer's website. The crawler indexes every page into the knowledge base automatically.

```bash theme={"dark"}
curl -X POST https://api.open.cx/crawl \
  -H "Authorization: Bearer ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://acmetours.com",
    "page_limit": 500,
    "auto_start_crawl": true,
    "crawl_interval_hours": 168
  }'
```

You can check crawl progress at any time:

```bash theme={"dark"}
curl https://api.open.cx/crawl/DATASOURCE_ID \
  -H "Authorization: Bearer ORG_API_KEY"
```

Or sync a single page without a full crawl:

```bash theme={"dark"}
curl -X POST https://api.open.cx/crawl/DATASOURCE_ID/pages/sync \
  -H "Authorization: Bearer ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://acmetours.com/faq" }'
```

<Tip>
  See all available parameters and endpoints in the [Crawl API Reference](/api-reference/crawl/create-datasource).
</Tip>

***

## Step 4: Add custom training

Website content gives the AI factual knowledge. **Training scenarios** teach it *how to behave* — tone, policies, edge cases, and workflows.

```bash theme={"dark"}
curl -X POST https://api.open.cx/training \
  -H "Authorization: Bearer ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cancellation policy",
    "content": "Customers can cancel up to 24 hours before their tour for a full refund. Cancellations within 24 hours receive a 50% refund. No-shows are non-refundable."
  }'
```

Use `"type": "BEHAVIORAL"` for always-active instructions (tone, guardrails) that apply to every conversation:

```bash theme={"dark"}
curl -X POST https://api.open.cx/training \
  -H "Authorization: Bearer ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Brand voice",
    "content": "Always be warm and friendly. Use the customer'\''s first name. Never use corporate jargon.",
    "type": "BEHAVIORAL"
  }'
```

<Tip>
  See all training types, directory management, and search in the [Training API Reference](/api-reference/training/create).
</Tip>

***

## Step 5: Grant dashboard access

Your customers need dashboard access to manage their inbox, handle human handoffs, and review conversations. Use **Login Links** to give them frictionless access — no emails, no forms, no org picker.

```bash theme={"dark"}
curl -X POST https://api.open.cx/partner/v1/orgs/ORG_ID/login-links \
  -H "Authorization: Bearer YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "owner@acmetours.com", "name": "Jane Smith" }'
```

The response contains a short-lived URL:

```json theme={"dark"}
{
  "url": "https://platform.open.cx/partner-login?token=a1b2c3...",
  "expires_at": "2026-04-12T12:15:00.000Z"
}
```

Redirect the user's browser to the returned `url`. If no account exists, one is created automatically. The user lands directly in the dashboard with **your partner branding** (logo, app name) — not the OpenCX defaults.

<Note>
  Login links expire after **15 minutes** and are **single-use**. Generate a new link each time a user needs to access the dashboard from your platform.
</Note>

<Tip>
  Login links are ideal for embedding a "Manage support" button in your own platform. See the [Login Links API Reference](/partners/api-reference#create-login-link) for full details.
</Tip>

***

## Step 6: Embed the widget

Use the `widget_token` from step 1 to embed the chat widget on your customer's site.

```html theme={"dark"}
<script
  src="https://cloud.opencopilot.so/widget.js"
  data-token="WIDGET_TOKEN"
></script>
```

Or with React:

```bash theme={"dark"}
npm install @opencx/widget-react
```

```tsx theme={"dark"}
import { Widget } from '@opencx/widget-react';

function App() {
  return <Widget token="WIDGET_TOKEN" />;
}
```

If your customers have logged-in users, you can authenticate them so the AI has context:

```bash theme={"dark"}
curl -X POST https://api.open.cx/widget/authenticate-user \
  -H "Authorization: Bearer ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Smith"
  }'
```

<Tip>
  See the full widget setup and authentication options in the [Widget docs](/widget/introduction) and [Widget Authentication API](/api-reference/widget/authenticate-contact).
</Tip>

***

## Putting it all together

Here's a complete example that provisions a customer from scratch:

<CodeGroup>
  ```javascript Node.js theme={"dark"}
  const PARTNER_KEY = 'YOUR_PARTNER_API_KEY';
  const BASE = 'https://api.open.cx';

  async function provisionCustomer({ name, externalId, website, instructions }) {
    // 1. Create the org
    const orgRes = await fetch(`${BASE}/partner/v1/orgs`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${PARTNER_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        name,
        external_id: externalId,
        website,
        ai_instructions: instructions,
      }),
    });
    const org = await orgRes.json();
    console.log(`Created org: ${org.id}`);

    // 2. Create an org API key
    const keyRes = await fetch(`${BASE}/partner/v1/orgs/${org.id}/api-keys`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${PARTNER_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ name: 'Production' }),
    });
    const { api_key: orgApiKey } = await keyRes.json();

    // 3. Crawl the website
    await fetch(`${BASE}/crawl`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${orgApiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        url: website,
        page_limit: 500,
        auto_start_crawl: true,
      }),
    });
    console.log(`Started crawling: ${website}`);

    // 4. Add behavioral training
    await fetch(`${BASE}/training`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${orgApiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        title: 'Brand voice',
        content: `You are a support agent for ${name}. Be helpful, friendly, and concise.`,
        type: 'BEHAVIORAL',
      }),
    });
    console.log('Added behavioral training');

    // 5. Generate a login link for the customer
    const loginRes = await fetch(`${BASE}/partner/v1/orgs/${org.id}/login-links`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${PARTNER_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        email: `admin@${name.toLowerCase().replace(/\s+/g, '')}.com`,
        name: 'Admin',
      }),
    });
    const { url: loginUrl } = await loginRes.json();
    console.log(`Login link: ${loginUrl}`);

    // 6. Return the widget token and login URL
    return { orgId: org.id, widgetToken: org.widget_token, loginUrl };
  }

  // Usage
  const { widgetToken } = await provisionCustomer({
    name: 'Acme Tours',
    externalId: 'acme-123',
    website: 'https://acmetours.com',
    instructions: 'Help customers with tour bookings and questions.',
  });
  ```

  ```python Python theme={"dark"}
  import requests

  PARTNER_KEY = 'YOUR_PARTNER_API_KEY'
  BASE = 'https://api.open.cx'

  def provision_customer(name, external_id, website, instructions):
      # 1. Create the org
      org = requests.post(
          f'{BASE}/partner/v1/orgs',
          headers={'Authorization': f'Bearer {PARTNER_KEY}'},
          json={
              'name': name,
              'external_id': external_id,
              'website': website,
              'ai_instructions': instructions,
          },
      ).json()
      print(f"Created org: {org['id']}")

      # 2. Create an org API key
      key_res = requests.post(
          f'{BASE}/partner/v1/orgs/{org["id"]}/api-keys',
          headers={'Authorization': f'Bearer {PARTNER_KEY}'},
          json={'name': 'Production'},
      ).json()
      org_api_key = key_res['api_key']
      headers = {'Authorization': f'Bearer {org_api_key}'}

      # 3. Crawl the website
      requests.post(
          f'{BASE}/crawl',
          headers=headers,
          json={'url': website, 'page_limit': 500, 'auto_start_crawl': True},
      )
      print(f'Started crawling: {website}')

      # 4. Add behavioral training
      requests.post(
          f'{BASE}/training',
          headers=headers,
          json={
              'title': 'Brand voice',
              'content': f'You are a support agent for {name}. Be helpful and concise.',
              'type': 'BEHAVIORAL',
          },
      )
      print('Added behavioral training')

      # 5. Generate a login link for the customer
      login_res = requests.post(
          f'{BASE}/partner/v1/orgs/{org["id"]}/login-links',
          headers={'Authorization': f'Bearer {PARTNER_KEY}'},
          json={
              'email': f'admin@{name.lower().replace(" ", "")}.com',
              'name': 'Admin',
          },
      ).json()
      print(f'Login link: {login_res["url"]}')

      return {'org_id': org['id'], 'widget_token': org['widget_token'], 'login_url': login_res['url']}

  result = provision_customer(
      name='Acme Tours',
      external_id='acme-123',
      website='https://acmetours.com',
      instructions='Help customers with tour bookings and questions.',
  )
  ```
</CodeGroup>

***

## What's next

After provisioning, the org is fully operational. The AI will:

1. **Answer questions** using crawled website content and training scenarios
2. **Hand off to humans** when it can't resolve an issue (configurable via [Handoff settings](/handoff/introduction))
3. **Re-crawl** the website on the configured interval to stay up to date

For advanced configuration:

<CardGroup>
  <Card title="Autopilot Settings" icon="robot" href="/api-reference/autopilot/get">
    Configure which channels the AI operates on and its behavior mode.
  </Card>

  <Card title="Office Hours" icon="clock" href="/api-reference/office-hours/get">
    Set business hours — the AI behaves differently outside office hours.
  </Card>

  <Card title="Tags" icon="tag" href="/api-reference/tags/list">
    Auto-tag conversations for categorization and reporting.
  </Card>

  <Card title="Contacts" icon="users" href="/api-reference/contacts/list">
    Manage customer contacts and their metadata.
  </Card>
</CardGroup>


# Partner Platform
Source: https://docs.open.cx/partners/introduction

Distribute AI-powered customer support to your merchants, tenants, or customers at scale.

The Partner Platform lets you **programmatically create and manage OpenCX organizations** for your customers. Each organization gets its own AI agent, chat widget, knowledge base, and integrations — fully isolated and ready to serve end-users.

## How it works

You integrate our Partner API into your platform. When a customer signs up (or you onboard them), you call a single endpoint to provision their AI support org. They get a widget token to embed on their site — that's it.

```mermaid theme={"dark"}
sequenceDiagram
    participant P as Your Platform
    participant API as Partner API
    participant Org as Customer Org

    P->>API: POST /partner/v1/orgs
    API->>Org: Create org + apply defaults
    API-->>P: { id, name, widget_token }
    P->>P: Embed widget with widget_token
```

## What you get

<CardGroup>
  <Card title="Single API call" icon="bolt">
    One POST creates a fully configured org with AI agent, widget token, and optional integrations.
  </Card>

  <Card title="White-label dashboard" icon="palette">
    Your logo, your app name, your support email — across the entire dashboard.
  </Card>

  <Card title="Full API access" icon="code">
    Every org gets its own API key. Train the AI, crawl websites, manage contacts — all via API.
  </Card>

  <Card title="Unlimited scale" icon="chart-line">
    Provision 10 orgs or 25,000 — the API handles it.
  </Card>
</CardGroup>

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/partners/quickstart">
    Create your first partner org in under 5 minutes.
  </Card>

  <Card title="Integration Guide" icon="map" href="/partners/integration-guide">
    End-to-end guide: from API key to a fully trained, live AI agent.
  </Card>

  <Card title="Admin Console" icon="gauge" href="/partners/admin-console">
    The dashboard page where you monitor and manage every connected customer org.
  </Card>

  <Card title="API Reference" icon="code" href="/partners/api-reference">
    Full endpoint documentation with examples.
  </Card>

  <Card title="Branding" icon="paintbrush" href="/partners/branding">
    Configure your logo, app name, and support email.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.open.cx/partners/quickstart

Create your first partner-managed OpenCX org via the Partner API in under 5 minutes — provision a key, create an org, and send a test message.

<Steps>
  <Step title="Get your API key">
    Partner API keys are provisioned by the OpenCX team during onboarding. You'll receive a JWT token that authenticates all Partner API requests.

    <Note>
      Partner API keys are separate from org-level API keys. They manage orgs (create, list, generate API keys, generate login links) — they cannot access chat sessions, contacts, or other org data.
    </Note>
  </Step>

  <Step title="Create an org">
    Call the Partner API to create an org for one of your customers:

    New customer orgs record your partner organization as their billing owner. If your partner account has no organization linked yet, OpenCX automatically creates one using your partner name and reuses it for future customer orgs. No additional request fields are needed.

    Existing designated OpenCX staff accounts are added as Admins to the automatically created partner organization. Customer organization memberships are unchanged.

    <CodeGroup>
      ```bash cURL theme={"dark"}
      curl -X POST https://api.open.cx/partner/v1/orgs \
        -H "Authorization: Bearer YOUR_PARTNER_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "Sunset Kayak Tours",
          "external_id": "customer-12345",
          "website": "https://sunsetkayak.com",
          "language": "en",
          "ai_instructions": "You are the support agent for Sunset Kayak Tours. Help customers with booking questions, availability, and tour information. Be friendly and concise."
        }'
      ```

      ```javascript Node.js theme={"dark"}
      const response = await fetch('https://api.open.cx/partner/v1/orgs', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_PARTNER_API_KEY',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          name: 'Sunset Kayak Tours',
          external_id: 'customer-12345',
          website: 'https://sunsetkayak.com',
          language: 'en',
          ai_instructions: 'You are the support agent for Sunset Kayak Tours. Help customers with booking questions, availability, and tour information. Be friendly and concise.',
        }),
      });

      const org = await response.json();
      console.log(org.id);           // org UUID
      console.log(org.widget_token); // widget embed token
      ```

      ```python Python theme={"dark"}
      import requests

      response = requests.post(
          'https://api.open.cx/partner/v1/orgs',
          headers={'Authorization': 'Bearer YOUR_PARTNER_API_KEY'},
          json={
              'name': 'Sunset Kayak Tours',
              'external_id': 'customer-12345',
              'website': 'https://sunsetkayak.com',
              'language': 'en',
              'ai_instructions': 'You are the support agent for Sunset Kayak Tours. Help customers with booking questions, availability, and tour information. Be friendly and concise.',
          },
      )

      org = response.json()
      print(org['widget_token'])  # widget embed token
      ```
    </CodeGroup>

    The response contains everything you need:

    ```json theme={"dark"}
    {
      "id": "a1b2c3d4-...",
      "name": "Sunset Kayak Tours",
      "widget_token": "f8e7d6c5b4a3...",
      "external_id": "customer-12345"
    }
    ```
  </Step>

  <Step title="Embed the widget">
    Use the `widget_token` from the response to embed the chat widget on the customer's site:

    ```html theme={"dark"}
    <script
      src="https://cloud.opencopilot.so/widget.js"
      data-token="f8e7d6c5b4a3..."
    ></script>
    ```

    Or with React:

    ```tsx theme={"dark"}
    import { Widget } from '@opencx/widget-react';

    function App() {
      return <Widget token="f8e7d6c5b4a3..." />;
    }
    ```
  </Step>

  <Step title="Verify">
    Open the customer's site. The chat widget should appear and the AI agent will respond using the instructions you provided.

    For a production-ready setup, follow the [Integration Guide](/partners/integration-guide) to train the AI with real content.
  </Step>
</Steps>

## Next steps

<CardGroup>
  <Card title="Integration Guide" icon="map" href="/partners/integration-guide">
    Full end-to-end setup: crawl websites, train the AI, authenticate users.
  </Card>

  <Card title="API Reference" icon="code" href="/partners/api-reference">
    Full endpoint documentation and error codes.
  </Card>
</CardGroup>


# Agent Configuration
Source: https://docs.open.cx/phone/agent-config

Configure your AI phone agent — voice, language, instructions, flow builder, knowledge sources, actions, transfer destinations, and telephony routing.

Changing phone agent settings requires **Voice settings** write access.

Edit any agent from **[Channels → Phone → Agents](https://platform.open.cx/channels/phone/agents)**.

<Tip>
  Haven't created an agent yet? Start with [Create Phone Agent](/phone/create-agent).
</Tip>

## Voice And Language

| Setting | Detail |
| - | - |
| **Voice** | Select from the voice library. Each voice has a distinct tone and style. |
| **Language** | Pick one or more languages in any combination, for example **Arabic (Saudi)** with **English**. Multi-language agents detect and switch languages automatically during the call. |
| **Background noise** | Optional ambient noise preset: `none`, `office`, `bar`, or `city-street`. Adds realism to the call. |

Use the play button beside a voice to hear a sample. When samples are available for
several of your agent's languages, choose one from the preview menu. Voices with
language-specific samples use English when none of the configured languages has a sample.

For Jordanian Arabic, select **Arabic (Jordan)** and choose **Saqer** or **Abdallah** from the voice library. Both use their recorded speaking pace, so their voice speed control is disabled. Use a test call to hear the voice before assigning the agent to a phone number.

When Arabic is one of the agent's languages, the agent estimates from the caller's first few turns whether they sound male or female, and uses matching Arabic grammar when it addresses them. What the caller says about themselves and your instructions take priority. For example, add "Always address callers in the feminine form" to override the estimate.

## Response Timing And Interruptions

For supported agents enabled by OpenCX staff, the agent can begin preparing a
reply while your speech is still being finalized. It waits for confirmed speech
before speaking or taking an action. If you continue speaking or correct a
number, the prepared reply can be discarded and generated again.

The agent also distinguishes brief acknowledgements from attempts to interrupt.
This can reduce unnecessary stops, but background speech or an acknowledgement
can still be misclassified. Test short acknowledgements, deliberate interruptions,
and numbers spoken with pauses. Check both browser and phone calls before
assigning the agent to a live phone number.

## Instructions

Define what the agent does during a call. Two approaches:

<Tabs>
  <Tab title="Free text">
    Write natural-language instructions in the text field. The agent follows them as guidelines throughout the call.
  </Tab>

  <Tab title="Visual flow builder">
    Build a structured call flow using drag-and-drop nodes:

    | Node | Purpose |
    | - | - |
    | **Root** | Entry point of the flow |
    | **Instruction** | Give the agent a directive at this step |
    | **Collect Info** | Ask the caller for specific information |
    | **Transfer Call** | Transfer to a phone number, SIP destination, or hang up |
    | **Call Action** | Trigger a workflow or tool |
    | **If Condition** | Branch based on what the caller said or data collected |
    | **End Call** | End the call |

    The flow builder and free-text instructions can be used together. Flow nodes override free text when active.
  </Tab>
</Tabs>

## First Message

The opening greeting when the call connects. Outbound answer detection runs in the background while the agent greets the recipient. Set this to a greeting that matches your brand (e.g. "Thanks for calling Acme. How can I help you today?"). Defaults to **"Hello?"** if left blank.

## Saving And Preparation

Click **Save** to store your changes. Save becomes unavailable briefly, and a
loading indicator appears inside **Test**. Once your changes are saved, Save
becomes available again. If preparation is still needed, the same Test indicator
continues; hover over it or focus it with the keyboard for an explanation.
Nothing opens automatically, and you can continue editing while preparation runs.

When your agent is ready immediately after saving, an **Agent saved** confirmation
appears. Otherwise, Test simply becomes available when preparation finishes,
without another notification.

**Test** becomes available as soon as the preparation required by the saved
settings is complete. Knowledge only needs preparing when the agent searches it
(see [Knowledge Sources](#knowledge-sources)); voice instructions still need to
finish preparing where applicable. When you remove sources so the rest is loaded
up front, Test becomes available as soon as you save, even if earlier preparation
had not finished. Browser and phone tests use the same readiness check, including
after reloading the page.

Saving unchanged settings reuses completed preparation. If no preparation is
required, **Test** is available as soon as the save finishes. Real customer calls
continue using the available instructions and knowledge while preparation runs;
this waiting period applies to testing.

## Knowledge Sources

Choose the instructions and knowledge the agent can use during calls. The agent
uses only what you check here: a new agent knows nothing beyond its own
instructions until you select sources.

* Check **individual items** or **entire folders**, under **Instructions** and
  **Knowledge**.
* Only **published** (non-draft) items that are available for voice sessions are
  used.
* Checking a folder includes all current and future items within it. Folders and
  instructions created later outside your selection stay out until you check them.

After you save, the agent's use of the selection depends on its size:

* **Nothing selected**: the agent follows only its own instructions.
* **The selection fits**: everything selected is loaded at the start of each call,
  so the agent can answer from it right away.
* **The selection is too large**: the agent looks up what it needs during calls.
  It is prepared in the background after you save, and **Test** becomes available
  when preparation finishes.

The size is checked each time you save the agent. If a selected folder grows past
what fits, save the agent again so it switches to looking things up: until then,
sources past the limit are left out of calls.

When you set sources through the API or MCP, send the IDs of every instruction,
folder and knowledge item to use. An empty list means none.

<Note>
  Knowledge sources are managed under the **Knowledge Sources** section of the agent settings page.
  Agents that could use every source before selections became required kept
  access to the folders that existed then, selected for them.
</Note>

## Actions And Workflows

Select which **active AI-trigger workflows** the agent can use during calls. The AI decides when to trigger them based on the session context.

* A `null` selection means **all actions** are available.
* An empty selection means **no actions**.

## Transfer Destinations

<Tooltip>Transfer destinations</Tooltip> are defined at the **org level** and then assigned to individual agents. Phone numbers use <Tooltip>E.164</Tooltip> format.

| Type | Target |
| - | - |
| **Phone** | Transfer to an external phone number (E.164 format) |
| **SIP** | Transfer to a SIP URI with optional digest authentication |
| **Team** | Ring eligible teammates in the dashboard, optionally starting with a selected team. See [Human calling](/phone/human-calling) for availability and fallback. |
| **Custom** | End the call. This destination does not dial another party. |

Manage destinations under **Transfer Destinations** in the agent settings. Add the destinations the agent may use and describe when to choose each one in its instructions. Test both an answered transfer and an unavailable destination. Team routing may fall back to other available teammates; see [Human calling](/phone/human-calling).

### Failover transfer destination

**Failover transfer destination** is used for a critical technical failure during the call. If unset, the agent attempts the first allowed destination; with no destination, it ends the call. This is separate from the instructions for ordinary customer-requested handoffs. Test the selected destination before relying on it.

## Recording

Where available, enable **Call recording → Record calls** to keep audio for calls handled by the agent. Transcript messages and audio recording are separate. See [Recordings and transcripts](/phone/recordings-and-transcripts) for settings, permissions, and post-call timing.

## Telephony And Routing

<AccordionGroup>
  <Accordion title="Inbound Numbers" icon="phone-arrow-down-left">
    Assign one or more verified phone numbers to the agent. Each number can only be assigned to **one agent**. For BYOC numbers, configure SIP trunks under **[Settings → SIP](https://platform.open.cx/settings/sip)** and assign them here.
  </Accordion>

  <Accordion title="Outbound Caller" icon="phone-arrow-up-right">
    Set the caller number for outbound calls. Choose a hosted number or configure a custom SIP trunk. See [Outbound Calls](/phone/outbound-calls).
  </Accordion>

  <Accordion title="Agent ID" icon="fingerprint">
    Each agent has a unique **Agent ID** shown on the settings page. Use it with the <Tooltip>X-OPENCX-AGENT-ID</Tooltip> SIP header for dynamic routing from your own infrastructure. See [SIP Integration](/phone/sip-integration).
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Inbound Calls" icon="phone-arrow-down-left" href="/phone/inbound-calls">
    Call routing, session matching, and call behavior.
  </Card>

  <Card title="Outbound Calls" icon="phone-arrow-up-right" href="/phone/outbound-calls">
    Make calls from the dashboard, API, or workflows.
  </Card>

  <Card title="SIP Integration" icon="server" href="/phone/sip-integration">
    Inbound and outbound SIP trunks for BYOC.
  </Card>
</CardGroup>

For number verification and route selection, see [Numbers and routing](/phone/numbers-and-routing).


# AI phone agent setup
Source: https://docs.open.cx/phone/ai-phone-agent

Find the current create a phone agent guide, including setup, supported calling behavior, and links to related phone documentation.

The current guide is **[Create a phone agent](/phone/create-agent)**. Start there for setup and operating instructions.

For the complete guide list, see [Phone overview](/phone/introduction).


# Call answering and ringing settings
Source: https://docs.open.cx/phone/call-answering

Configure automatic answering, team call queues, fair distribution, ring timing, and team wrap-up durations.

Use **[Settings → Voice & Telephony](https://platform.open.cx/settings/telephony)** to choose how incoming customer calls reach your team. These settings apply to calls routed directly to human agents and calls handed off from an AI phone agent to your team.

## Before you start

Telephony must be enabled for your organization. Anyone with **Voice settings** write permission can open **Settings → Voice & Telephony** and turn on **Enable telephony**. This setting is available to every organization. This control grants access to telephony; numbers, routing, teams and agent availability still need to be configured. Turning it off does not cancel existing calls or release phone numbers.

To edit call answering settings, you need the **Voice settings** write permission. Agents also need the normal permissions and availability required to receive and accept calls.

## Automatically answer after a short ring

1. Open **Settings → Voice & Telephony**.
2. Turn on **Auto-answer calls**.
3. Set **Answer after** to a whole number from **1 to 20 seconds**.
4. Leave the field or press **Enter** to save. The auto-answer switch saves immediately.
5. Each agent opens their dashboard and allows microphone access when the browser requests it. The dashboard prepares automatic answering when the agent is available for calls, without a separate setup card. If the browser requires interaction to enable audio, click anywhere in the dashboard.

Auto-answer is off by default. The saved delay defaults to **2 seconds**. When enabled, the countdown starts when the call begins ringing your team. A ready agent's visible dashboard tab accepts the call at the end of the countdown without another click. The first successful acceptance connects; other agents stop ringing.

While the automatic-answer countdown is active, the incoming-call notification stays visible and its Accept and Reject controls are hidden. Manual controls remain available if automatic answering cannot prepare the microphone or the call has no automatic-answer deadline. There is no agent-level pause or opt-out; auto-answer is controlled by the organization setting. Settings are captured when each call starts ringing; changes apply to new rings.

<Note>
  Keep the dashboard open and visible. Preparation runs automatically when you are available for calls. The initial microphone check stops immediately; switching tabs reuses that check without reopening the microphone. Changes to availability, organization, or input devices require a fresh check. The microphone is checked again immediately before automatic acceptance; if access fails, the call stays available for manual answering. Reloading the dashboard starts a new preparation. Only one visible tab in the same browser can handle automatic answering at a time. Microphone permission, working audio and a browser that supports preparation are required. This does not auto-answer a desk phone, forwarded external number, teammate call, warm-transfer invitation or conference invitation.
</Note>

A busy agent or a call that has ended will not be automatically accepted. If preparation fails, the incoming call shows the problem. Allow microphone access in your browser and click in the dashboard to retry, or use **Accept** manually. Automatic answering does not bypass routing, availability or call permissions.

## Ring a percentage of available agents

Set **Available agents to ring** to a whole percentage from **1 to 100**, then leave the field or press **Enter** to save. The default is **100%**, preserving the behavior of ringing everyone eligible.

The percentage applies **after** the existing team, availability, busy and online checks. It is based on the agents eligible for that call, not total team membership. Open rounds up so there is at least one recipient whenever an eligible agent exists.

| Available agents | Percentage | Agents rung |
| - | - | - |
| 3 | 25% | 1 |
| 20 | 25% | 5 |
| 100 | 25% | 25 |
| 20 | 100% | 20 |

Agents already ringing for another call are excluded. Simultaneous incoming calls select separate available agents. Agents who were rung least recently are preferred. A call keeps the same selected recipients if their dashboards reconnect. With team telephony pacing off, this setting does not add successive ringing waves or expand to the rest of the team after a timeout. Unanswered calls follow the existing timeout or transfer-failure behavior.

## Team queues and telephony pacing

Open **Settings → Teams**, edit a support-enabled team, and find **Telephony pacing** below **Assignment pacing**. You need **Teams** write permission to change these settings. Route calls to a team transfer destination for its policy to apply.

Turn on **Telephony pacing** to offer each call to **one available teammate at a time**. Multiple calls can ring different teammates concurrently. If everyone is busy, calls wait for that team in arrival order; they do not spill into other teams. An agent already ringing, on a call, unavailable, or in wrap-up is excluded. Teammates must have **Available for calls** enabled and their dashboard open. Chat session capacity limits do not prevent eligible teammates from receiving phone calls.

| Setting | Default | Options |
| - | - | - |
| Telephony pacing | Off | On or off |
| Call distribution | Longest available | Longest available or Fewest answered calls today |
| Ring timeout (seconds) | 30 | 10–120 |
| Maximum queue wait (seconds) | 300 | 30–3,600 |
| Use organization wrap-up time | On | Inherit, or enter 0–3,600 seconds |

**Longest available** prioritizes the teammate who has been available and free from calls longest. **Fewest answered calls today** prioritizes the lowest number of connected calls for this team since midnight in your organization's timezone; ties use longest available. Unanswered offers do not count as answered calls. Daily totals do not adjust for different shift lengths.

If an offer is declined or expires, the call can be offered to another eligible teammate. The missed teammate has a 30-second cooldown. Queue processing can take approximately two seconds between offers. The maximum wait includes time spent ringing agents; when it expires, the unanswered call ends. This setting does not add position announcements, hold music, automatic callbacks, or overflow destinations.

With pacing on, the team offers each call to one agent regardless of **Available agents to ring**. Auto-answer starts a fresh countdown for each offer. If the remaining offer window is too short for that countdown, the agent can still answer manually. Calls already queued keep the timing and distribution settings captured when they entered the queue, even if pacing is subsequently switched off.

### Finishing wrap-up from a mini app

An approved mini app can save a wrap-up code, close the phone session, then [finish that session’s wrap-up](/api-reference/phone/finish_wrap_up) for the viewing teammate. This must be explicitly configured in the app: saving a structured field alone does not close a session or finish wrap-up. The action leaves unavailable teammates unavailable and cannot release wrap-up for a different session.

### Team wrap-up time

Leave **Use organization wrap-up time** on to inherit the setting in **Voice & Telephony**. Turn it off to enter a team-specific duration in seconds, including **0** for no wrap-up. Team wrap-up works with or without telephony pacing. Save the team to apply your changes.

The effective wrap-up duration is captured when human ringing starts. After the call ends, it prevents the teammate from receiving calls from any team during that window. Calls without a team use the organization default. The wrap-up strip counts elapsed time up from **0:00**. Extending the window keeps the same start time, and reloading restores it from the completed call. If older call data has no start time, the strip shows the remaining window instead. Agents can still finish wrap-up early with **I'm ready**.

## Test your setup

Start with a small team of available agents. Open one dashboard and allow microphone access, call a number routed to that team, and confirm that the countdown matches your saved delay and both sides can hear each other. Then turn off auto-answer in organization settings and confirm manual **Accept** still works. Test the ring percentage with several available agents and check that only the expected number of dashboards ring. For a paced team, place two calls with one available teammate: the second should wait. Decline the first offer with another teammate available and confirm it moves to them. Complete a call and verify the team’s wrap-up duration.

## Additional telephony options

The **Voice & Telephony** page also lists routing, assistance, IVR, queue, recording, reliability, after-hours, monitoring, dialer and integration options. Options marked **Contact us** open an email to your account team with the feature name included. They do not change call behavior. Contact your account team to discuss availability and setup. Links for existing capabilities open their current settings or calling surface.


# Classical IVR
Source: https://docs.open.cx/phone/call-flows

Build deterministic keypad menus with WAV recordings, identifier collection, working hours and team transfers.

Classical IVR runs a saved workflow when an assigned number receives a call. Key presses select explicit branches; a phone agent does not interpret them or rewrite your recordings.

## Enable and create

1. Open **Settings → Voice & Telephony** and enable telephony.
2. Turn on **Enable Classical IVR** on the same settings page. This makes the IVR trigger and nodes available in Workflows.
3. Open **Channels → Phone**. The page contains **AI phone agents** followed by **Classical IVR**. Use the Classical IVR section to manage workflows, recordings and phone-number assignments. This section is hidden while Classical IVR is disabled.
4. Open the **WAV recordings** tab to upload recordings. In the **Workflows** tab, select **Create IVR**. The editor starts with the **IVR Incoming Call** trigger.
5. Build the flow, save a version and activate it.
6. Use **Test call** in the **Workflows** tab before assigning a phone number. After testing, use the searchable **Phone numbers** selector on the workflow row to assign one or more numbers. The selector shows each number’s name and phone number, and you can search by either. Deselect a number to remove its assignment. Numbers assigned to another IVR are labeled; selecting one moves it to this IVR.

Only verified phone numbers can be assigned. Each phone number can have only one inbound destination: an IVR or an AI phone agent. Numbers assigned to a phone agent cannot be selected for an IVR until you unassign them from that agent, and vice versa. **Settings → Phone Numbers → Inbound destination** shows the assigned IVR or agent name. Assignment changes display **Applying routing…** while they are saved and applied to incoming calls.

The **IVR Incoming Call** trigger runs only for calls to numbers assigned in the workflow row’s **Phone numbers** selector. It does not subscribe to other inbound calls, outbound calls or AI phone-agent calls. The workflow list shows each IVR’s assigned numbers in a scrollable table with 10 workflows per page. Use the page controls below the table to browse additional workflows.

You need workflow read permission to view flows and recordings, and workflow write permission to upload recordings, edit flows or start a test call. Assigning a number also requires voice-channel settings write permission.

<Warning>
  A browser test runs the active flow, including its lookup and session actions. Team transfers ring real available teammates. Use a test organization or test teams when you need isolation.
</Warning>

Turning Classical IVR off preserves workflows, recordings and number assignments. New calls use the number’s usual routing until Classical IVR is enabled again. Changing this setting requires Voice & Telephony write access.

## Classical IVR nodes

| Node | Purpose | Next step |
| - | - | - |
| Play WAV recording | Play an uploaded recording without changing its words | Branch on `completed` or `error` |
| Keypad Menu | Collect one allowed key | Branch on `outcome` and `digits` |
| Collect Digits | Collect an identifier or callback number | Confirm input before using it for a lookup |
| Speak Text | Read fixed text or repeat a workflow value | Select a language; enable digit-by-digit reading for identifiers |
| Transfer Call | Ring a team, transfer to an external phone-number destination, or connect a SIP destination | An answer ends the flow by default; team transfers can opt into post-call steps; SIP transfers always continue the flow |
| Save Keypad CSAT Rating | Save a collected 1–5 rating to native CSAT reporting | Reference a completed keypad step in this IVR run |
| Record Voicemail | Play a greeting and tone, then save caller audio and a callback number for a team | Branch on `completed`, `no_input` or `error`, then end the call |
| End Call | End the call | No later steps run |

Use existing workflow condition, working-hours, contact lookup and session-note actions alongside these nodes. For example: menu → collect VAT → repeat digits → confirmation menu → contact lookup → team transfer. A VAT match identifies a record; it does not prove the caller is authorized to access it.

## WAV recordings

Upload mono or stereo WAV files with 16-bit PCM, A-law or mu-law encoding. Supported sample rates are 8, 16, 24, 32, 44.1 and 48 kHz. Files must be at most **20 MB** and **five minutes** long. Unsupported or malformed files are rejected.

Uploads are automatically compressed for speech playback. Keep uploading WAV files; no conversion is needed on your side. Each recording is fully loaded before playback, and playback buffers are released when it finishes or is interrupted. Existing uploaded recordings remain playable.

Keypad Menu and Collect Digits have two recording selectors: **Menu WAV recording** plays the main prompt, while **Retry WAV recording (optional)** plays before a retry after missing or invalid keypad input. Leave the main recording empty to use menu text; leave the retry recording empty to repeat the menu without an extra recording.

You can also select **Upload WAV recording** beside a workflow node’s recording selector. The modal lets you preview a WAV before uploading; the new recording is selected automatically for that node.

The recordings table shows 10 recordings per page in a scrollable area. Use the page controls below the table to browse additional recordings. Uploading a recording returns you to the first page.

Select **Preview** to listen before using a recording. Each upload creates a new recording. To replace a recording, upload a new file and select it in a new workflow version. Existing calls keep the workflow version and recording references they started with.

For keypad menus, either select a WAV recording or enter fixed menu text and its two-letter language code. A WAV recording takes precedence when both are supplied. Speak Text reads exactly the supplied text; it does not compose a response.

## Input and retries

* Menus collect one key. Set **Allowed menu keys**, for example `1239`.
* Digit collection accepts 1–32 digits. Keep identifiers as text to preserve leading zeros.
* Input completes when its maximum length is reached or the caller presses the configured finish key. Fixed-length input can use **None** as its finish key.
* To accept variable-length input without requiring `#`, enable **Submit after a pause** and set **Inter-digit timeout (seconds)**. Once the minimum digit count is met, that pause submits the entered digits. This option is off by default; missing or shorter input still follows the timeout branch. Set the minimum length carefully to avoid treating an incomplete identifier as complete.
* No-input timeout defaults to 10 seconds; the pause allowed between digits defaults to 5 seconds.
* Maximum attempts defaults to 3 and can be set from 1 to 5. Use **Retry WAV recording** to select or upload the recording played after missing or invalid input.
* Keys may interrupt playback when **Allow keys during playback** is enabled, once the prompt starts playing. Keys pressed while a prompt is loading are ignored.
* With **Allow keys during playback** disabled, callers must wait for the entire prompt before entering input. Use this for instructions that must be heard before a selection, such as consent. The no-input timeout starts after playback finishes.
* Keys pressed between workflow steps are recorded as ignored; they are never carried into the next menu or identifier. Wait for the next prompt before entering the next value.

Branch explicitly for `input`, `no_input`, `invalid`, `inter_digit_timeout` and `error`. With **Submit after a pause** off, a pause before completion never produces successful input. Retrying collection starts with an empty digit buffer. Route missing or invalid identifiers to your chosen fallback; do not treat an input error as the caller declining consent or cancelling a callback.

## Voicemail for a team

**Record Voicemail** is available in IVR workflows after voicemail support has been enabled in your deployment. Existing callback menus require this action to record a message; saving a callback number alone does not start recording.

1. Upload your voicemail greeting under **WAV recordings**. Include the instructions for leaving a message; the action plays the tone automatically after the greeting.
2. Add **Record Voicemail** after your callback-number selection. Select the greeting and the receiving support team.
3. Set **Callback number** to a full international number beginning with `+`, such as `+35722123456`, and select **Number source**:
   * **Caller number**: map the incoming caller number. If caller ID is withheld or unusable, route to number collection first.
   * **Entered number**: use **Collect Digits**, validate and normalize the entered number, then pass the full international number to the action. Keypad entry cannot include `+`; add it after collecting a country code, or apply the correct country prefix for local input. This callback number does not replace the contact's saved phone number.
4. Set **Maximum message length (seconds)**, **Wait for speech (seconds)**, **Finish after silence (seconds)** and **Finish key**. Defaults are 180 seconds, 10 seconds, 5 seconds and `#` respectively. Maximum message length accepts 10–300 seconds.
5. Follow the action with **End Call**, optionally preceded by a confirmation on `completed` or a retry/fallback on `error`. Complete any required recording-consent steps before this action.

**Keep IVR unrecorded** controls the full-call recording; Record Voicemail explicitly records the message even when that setting is on. Use that setting when the greeting and menus should also be absent from the separate full-call recording.

Only the caller's incoming audio after the tone is saved. The greeting and other IVR playback are excluded. Recording finishes when the caller hangs up, presses the finish key, reaches the maximum length, or stops speaking for the configured period. Keys pressed during the greeting or tone do not finish the message.

The selected team receives an open session containing the callback number and a playable **Voicemail** card in the call history. Agents need session read permission to view it; calling back uses the usual outbound-call permissions. Ending the phone call leaves the session open for the team to handle. Delivery retries preserve later agent changes. Moving a voicemail session to a different team runs team-change workflows. If delivery reopens a closed session, its history records the system reopen and session-reopened workflows run. Deleting a team preserves its historical voicemail; if the selected team is removed or disabled before delivery, the session appears unassigned for follow-up.

An empty message returns `no_input`: callback details remain available and the card says no spoken message was recorded. Interrupted recordings show an incomplete or failed state and retain any recoverable audio. If the recording process disappears unexpectedly, recovery runs after ten minutes of inactivity. Temporary audio is cleaned up after completion; deleting the session also schedules its voicemail audio for deletion.

Configure country-to-team routing in the workflow before this action. The receiving team is explicit and does not depend on the callback number's country code.

## Business hours and holidays

Add **Get Custom Working Hours** to read a named schedule from **Settings → Office Hours**. Branch on `isHoliday` for holiday handling, then `isNowWithinHours` for regular open/closed handling. Use `exceptionName` in internal notes when useful. Keep dates, recurring holidays and opening periods in the schedule rather than duplicating them in workflow code. See [Office hours and holidays](/api-reference/office-hours/index).

## Transfers and version changes

Transfer Call uses an existing team, phone-number or SIP transfer destination. Team transfers use the team’s availability and ring settings. By default, an actual teammate joining ends the IVR and leaves the human call connected. When no eligible teammates exist, or nobody answers, the workflow continues with `no_eligible_agents` or `no_answer`. Add a callback-choice branch or a closing message for those outcomes.

For an external transfer, choose a **Phone Number** destination containing a full international number beginning with `+`. The incoming telephone carrier must support transferring the call. Browser preview calls and extensions are not supported by this IVR action; to keep the caller on the OpenCX call, use a SIP destination instead (see below). A successful carrier handoff returns `transferred` and ends the IVR; it does not confirm that a person answered. A rejected transfer returns `error`, so add a fallback branch. After handoff, OpenCX no longer controls the remote call’s recording, whisper or queue behavior. **Record human call** applies to OpenCX team and SIP transfers, not to external phone transfers.

For a team transfer, optionally select **Agent whisper recording**. The picker lists uploaded recordings of at most 15 seconds. After a teammate accepts, the dashboard plays it privately before joining the caller. It is not published into the call or included in the call recording. If the recording cannot be loaded, acceptance continues without an announcement. If browser playback is blocked or fails, the teammate sees a warning and the call connects without the announcement; a stalled playback is limited to 20 seconds. Use headphones and enable browser call audio before testing auto-answer. Switching organizations during the announcement ends the accepted call, so it cannot remain assigned without a teammate. Browser refresh/recovery after joining does not replay the whisper.

Activating a new version applies to new calls. Removing a number's call-flow assignment restores its other configured routing. Unassign a flow from its numbers before deactivating it.

Browser tests use your microphone, speakers and the on-screen keypad. They verify the call media and workflow behavior without changing number assignments. A successful browser test does not verify a carrier connection; test a real incoming call before rollout.

When an IVR-only call ends, its final status and duration are saved before Phone Call Finished workflows run. The session closes unless the call has entered a Record Voicemail action, which leaves it open for the receiving team. A successful team transfer keeps the human call open until it ends.

## Transfers to a SIP destination

Choose a **SIP** destination to connect the caller to an external SIP endpoint, such as an external virtual assistant or another contact center, without handing the call away. The caller stays on the OpenCX call while the destination talks to them, so the session keeps one call, one recording and one transcript, and the IVR decides what happens next:

| Outcome | When | What to add after it |
| - | - | - |
| `handed_back` | The destination returned the caller through [Hand back a call](/api-reference/phone/hand_back_call) | Usually a team Transfer Call. Its teammate sees the summary the destination sent |
| `completed` | The destination hung up | A closing message, a keypad survey, or End Call |
| `no_answer` | The destination did not answer, was busy or declined | A fallback transfer or a message |
| `error` | The call could not be placed, for example a rejected caller ID or a broken route | A fallback transfer or a message |

The destination is hung up as soon as its hand-back is accepted, before the next step runs, so it never hears the rest of the call; if it cannot be hung up, the call ends instead of continuing. A hand-back is accepted only after the destination answered. If the caller hangs up during the transfer, the destination is hung up too and the flow ends. A transfer lasts at most three hours.

Recording follows the same rules as a team transfer: with **Keep IVR unrecorded** enabled, the answered transfer is recorded only when **Record human call** is `true`, and the recording continues after a hand-back into the teammate's call. When the destination hangs up and the flow continues, the recording stops first, as it does before a post-call survey. When live transcripts are enabled for your organization, the destination's speech appears in session history under the destination's name.

### SIP headers from the workflow

Use **SIP headers (optional)** on Transfer Call to send values from earlier steps, such as the dialed number from the trigger or a customer tier from a lookup, as custom `X-` headers. Headers apply to external phone and SIP transfers.

* Every transfer carries the session ID as `X-OPENCX-SESSION-ID`, unless a SIP destination's allowed headers leave it out. Destinations that hand calls back need it, so add it to their list.
* A header whose value is empty when the step runs is not sent. Names must start with `X-` and cannot start with `X-OPENCX-`; values are up to 255 printable characters; a step can set up to 20 headers.
* A header the SIP destination already sends from its own settings cannot be set again by the workflow, and neither can `X-Zendesk-Ticket-Id`, which comes from the session.
* A SIP destination with **Send only allowed headers** receives only the names on its list, the session ID included. SIP transfers send no other headers: not the organization's internal identifiers, and not the headers that arrived on the caller's call.

Configure caller ID, encryption and allowed headers on the destination; see [SIP transfer destinations](/phone/sip-integration#sip-transfer-destinations).

## Post-call keypad surveys

For team transfers, enable **Continue IVR after the human call** on Transfer Call. The IVR stays silent while the teammate speaks with the caller. When the teammate clicks **End call**, the teammate leaves and begins their normal wrap-up; the caller stays connected to hear the following IVR steps. The human-call recording is stopped before the survey starts. Call duration includes the caller’s time in the survey; teammate wrap-up starts when the human call ends.

Build the survey in the same incoming-call workflow:

1. Optionally play your survey invitation before Transfer Call.
2. Enable **Continue IVR after the human call** on the team transfer.
3. Branch on the transfer outcome. Run the survey only for `completed`; keep your existing fallback for failed or unanswered transfers.
4. Add a Keypad Menu using your rating recording, allowed keys `12345`, and finish key **None**. Configure missing-input and invalid-input branches separately.
5. On `input`, add **Save Keypad CSAT Rating** and supply that menu’s step ID. It reads the accepted digits from this run; it cannot submit an arbitrary score or use another session’s input.
6. Play your acknowledgement recording, then End Call. End missing or invalid responses without creating a rating.

Enable **Phone** in your CSAT settings before saving keypad ratings. This action saves the rating in native CSAT reporting and session history, with the session’s assigned teammate and team at submission time. It does not send an SMS. Review any resolution-triggered **Send CSAT** workflows and exclude phone sessions if you only want keypad surveys; those message actions still use SMS for phone sessions.

Continuation requires an explicit **End call** from the teammate. If the caller hangs up first, the survey is cancelled. A browser disconnect allows a 30-second reconnection period; it does not immediately start the survey. If the teammate does not reconnect and no continuation arrives, the call ends. External-number transfers do not support continuation because the remote call is outside OpenCX.

If the survey cannot start safely, **End call** still ends the call and starts teammate wrap-up. If another End request is already processing, a conflicting request can report an error; retry after that request finishes.

Leave continuation off for calls that should end normally. Activate and test a new workflow version only after the post-call capability is available. Test teammate-end, caller-end, invalid input, missing input, recording behavior and saved scores before assigning live numbers.

## Companion and API

Companion can author the same `ivr-incoming-call` workflows and use the Classical IVR node definitions. It can list/upload recordings and assign an active flow to a number. Review the flow before activation and number assignment.

API access uses `workflows:read` for listing recordings, `workflows:write` for uploading, and both `phone:write` and `workflows:write` for number assignment. Use existing workflow endpoints to create versions, validate and activate them. A SIP destination returns callers with `phone-calls:write`.

* [List recordings](/api-reference/call-flows/list-assets)
* [Upload a WAV recording](/api-reference/call-flows/upload-asset)
* [Assign a number](/api-reference/call-flows/set-binding)
* [Hand back a transferred call](/api-reference/phone/hand_back_call)

## Session history and call recordings

Open the call's session in **Inbox** to review the IVR. By default, recording includes the IVR and continues if the caller reaches a teammate. Recording availability depends on recording being enabled and processing completing successfully.

To collect recording consent without recording the menu:

1. Enable **Keep IVR unrecorded** on the **IVR Incoming Call** trigger.
2. Collect consent with a keypad menu and branch explicitly on the caller’s choice. Use a recording that explains that declining recording still connects the call.
3. Continue both choices to **Transfer Call**. Set **Record human call** to `true` only for an explicit acceptance. Set it to `false` for declined, missing or invalid consent.

With this setting enabled, recording starts only after a teammate accepts an approved transfer. Declining recording does not prevent routing or disconnect the caller. Without **Record human call** enabled, the accepted transfer stays unrecorded. Later teammate transfers in that same call keep the original recording decision. The call keeps the settings of the workflow version it started with.

Leaving **Keep IVR unrecorded** off preserves recording from the beginning of the IVR; a consent menu or transfer setting alone cannot undo audio already captured. This setting controls audio recording, not separately configured live transcripts.

Each IVR run appears as one **IVR selection** event in session history, collapsed by default. Expand it to review the timestamped prompts, key presses, and outcomes together. Actions are emphasized and long details are truncated; hover over or focus a step to read its full details:

* Prompt playback starts show the exact text or the uploaded recording's name. A start does not mean the caller heard the entire prompt.
* Key presses show the key, the associated menu prompt, and the attempt number. The event identifies keys that interrupted the prompt or were ignored while keypad input was disabled, including loading and transitions. A transition key is associated with the preceding command; it is not input to the next step.
* Each attempt records its result, including invalid input, no input, or a timeout between digits. Retry prompts appear inside the same expandable event.

When IVR recording is enabled, play the session's call recording to hear the audio around a selection. With **Keep IVR unrecorded** enabled, use the IVR selection events to review that portion of the call. Keep session events visible when reviewing session history. IVR selections stay grouped even when **Group similar events** is turned off. These entries are internal and are not sent to the caller. History is captured for new calls; earlier calls cannot be reconstructed from final workflow results alone.

## Troubleshooting

If Classical IVR is missing, check both telephony and Classical IVR enablement and your workflow permissions. If a recording will not play, check its preview and the call's workflow run. If a transfer fails, check the destination's team, available membership, business hours and call capacity. For a SIP destination, run **Test connection** on the destination, and check that the endpoint accepts the caller ID and headers it is sent. A hand-back that returns `409` arrived after the transfer ended; check the transfer's outcome in the workflow run. Use the IVR selection event and workflow step results to distinguish invalid input, lookup results and transfer failures.


# Phone call lifecycle and outcomes
Source: https://docs.open.cx/phone/call-outcomes

Understand call status, outcome, and disposition; use call completion events without assuming a connected call reached a person or has a final summary.

A phone attempt has a connection lifecycle and a result. Keep these separate from the session's resolved or unresolved status: a connected call does not prove the customer's request was resolved.

<Note>
  Disposition-based follow-ups require **Call → Disposition** in your workflow builder. If it is absent in your workspace, contact support before configuring these recipes. Existing **Outcome** values alone cannot distinguish busy, declined, and voicemail.
</Note>

## Status, outcome, and disposition

| Field | What it describes | Examples |
| - | - | - |
| Call status | The attempt's connection state | Initiating, ringing, in progress, completed, missed, no answer, busy, rejected, failed, canceled. |
| Workflow outcome | The broad way an AI call ended | `completed`, `transferred`, `unanswered`, `failed`. |
| Disposition | The more specific result supported by available evidence | `busy`, `voicemail`, `human_answered`, or `unknown`. |
| Session status | Whether the customer session remains open or has been closed | Independent of whether a person answered the phone. |

## Disposition reference

| Disposition | Meaning |
| - | - |
| `human_answered` | Answer detection identified a person on a connected call. |
| `no_answer` | The attempt ended without an answer. |
| `busy` | The call result explicitly reported a busy line. |
| `declined` | The call was rejected; the result does not necessarily identify who rejected it. |
| `voicemail` | Answer detection identified something other than a person: a voicemail greeting, a phone menu, a call-screening prompt, or a carrier announcement such as a full or unset mailbox. |
| `failed` | The attempt failed. |
| `canceled` | The attempt was canceled. |
| `unknown` | There is insufficient evidence to identify the answer type. |

Busy, declined, canceled, and voicemail attempts use the broad workflow outcome `unanswered`. A connected call can have `completed` with disposition `unknown`. Keep an explicit fallback branch instead of treating every unclassified call as answered by a person.

For outbound AI calls with answer detection, the agent starts its greeting after pickup while checking for voicemail in the background. Recipients do not need to speak first. When voicemail is detected, the agent stops speaking and ends the call; part of the opening may already have played. If detection is inconclusive or unavailable, the call continues normally. Test the languages and routes you use. In sequences, detected voicemail is a failed voice step with reason `voicemail`, and does not count as a reply that exits the journey. A connected call on which the recipient never speaks is recorded as no answer, not as a reply: only a call where the recipient actually spoke, or where answer detection identified a person, concludes the journey.

## Use Call Finished

The **Call Finished** trigger supports follow-ups after AI calls, including outbound attempts that fail before the agent speaks. It is separate from **Make phone call**, which starts a call and can wait for its outcome. See [Workflow call results](/phone/outbound-calls#workflow-call-results) for that action's statuses, timeout behavior, and guidance for updating existing workflows. Neither a completed call nor an immediate `success` result proves a person answered.

| Workflow field | Reference | Use |
| - | - | - |
| Call ID | `trigger.call.callId` | Identify an attempt when available. |
| Direction | `trigger.call.direction` | Restrict outbound follow-ups to `outbound`. |
| Disposition | `trigger.call.disposition` | Choose the follow-up branch. |
| Outcome | `trigger.call.outcome` | Preserve existing broad outcome rules. |
| End Time | `trigger.call.endTime` | Record when the call ended. |
| Duration | `trigger.call.duration` | Call duration; may be zero on failed attempts. |
| Summary | `trigger.call.summary` | Available summary text; may be empty. |
| Session ID | `trigger.call.ticket.ticketId` | Link the attempt to its OpenCX session. |
| Contact ID | `trigger.call.ticket.contact.id` | Select the OpenCX contact for a follow-up. |

<Warning>
  **Call Finished can run before the final summary is generated.** Log the outcome immediately if needed. Retrieve the finished session later before updating a CRM note with a final summary. A fixed delay alone is not proof that the summary is ready.
</Warning>

The `ticket` segment in workflow references is the existing field identifier for the session. Keep it unchanged in expressions.

## Webhooks and repeat attempts

External receivers can use [`phone_call.ended`](/api-reference/webhooks/types#phone-call-ended). Its optional `call_id` and `disposition` fields describe the attempt; workflow fields use `callId` instead. Check the actual payload before building rules for a human-call or legacy calling route.

A session may contain multiple attempts. Each AI call attempt can trigger its own **Call Finished** workflows; repeated completion events for the same attempt do not run them again. Store the attempt identifier alongside any CRM note or follow-up you create, and make your receiver handle repeated delivery without repeating that side effect. When a call ID is missing, review the event rather than grouping every call from that customer under one permanent deduplication key.

Continue with [Follow-up workflows](/phone/follow-up-workflows) for WhatsApp, callbacks, and CRM logging.

## Read evidence for a specific call

Add **Get Phone Call Details** after **Call Finished**, using `trigger.call.callId` and `trigger.call.ticket.ticketId`. The lookup checks both the session and organization and never substitutes a newer call.

The result provides recorded duration, queue waiting time, human pickup evidence, and the end actor when known. **Ended by** is `agent` for a recorded teammate end action, `system` for a completed IVR hang-up command, and `unknown` when neither is recorded. A teammate ending the human part and the IVR later ending a survey are separate events; the teammate ID remains available. Do not infer the end actor from the current assignee or from a generic disconnect.

Use **Answer time seconds** against the source queue's target in a workflow. For inbound calls, it measures the time from the first recorded invitation until an identified teammate joins the call, excluding the initial IVR. External phone transfers and conference participants do not count as teammate pickup. Accepting an invitation alone does not count as pickup; if no teammate join is recorded, pickup remains unconfirmed. For outbound calls, **Human answered** is false and the pickup and queue-timing fields are empty: a teammate joining does not establish that the customer answered. Calls without confirmed teammate pickup have no answer-time value. **Queue wait seconds** can describe an unanswered attempt when its end is recorded. An unanswered call is not automatically an abandoned call: use caller hang-up evidence before classifying abandonment. These fields do not create an aggregate service-level report or apply a chat reply SLA.


# Create Phone Agent
Source: https://docs.open.cx/phone/create-agent

Set up an AI voice agent — choose a voice, write instructions, assign a phone number, and make your first test call.

Create an AI voice agent entirely from your [OpenCX dashboard](https://platform.open.cx).

## Prerequisites

* **Voice settings** write access to create or change an agent.
* A **verified phone number** under **[Settings → Phone Numbers](https://platform.open.cx/settings/phone-numbers)** if you plan to assign an inbound number. Agents can also be created without a number for <Tooltip href="/phone/sip-integration">SIP</Tooltip>-only or outbound-only use.

## Go Live

<Steps>
  <Step title="Open The Phone Channel">
    Go to **[Channels → Phone](https://platform.open.cx/channels/phone)** and click **Create Agent**.
  </Step>

  <Step title="Name Your Agent">
    Give the agent a descriptive name (e.g. "Sales Qualifier", "Support Line").
  </Step>

  <Step title="Choose Voice And Language">
    Select a voice from the voice library and pick the languages the agent speaks, in any combination. Multi-language agents can switch languages during a call based on the caller. Optionally set a background noise preset (`office`, `bar`, `city-street`, or `none`).
  </Step>

  <Step title="Write Instructions">
    Define what the agent should do. You can write free-text instructions or use the <Tooltip href="/phone/agent-config">**visual flow builder**</Tooltip> to create a structured call flow with branching logic. See [Agent Configuration](/phone/agent-config) for details on both.
  </Step>

  <Step title="Set A First Message">
    Set the <Tooltip>first message</Tooltip> — this is the agent greeting for the call (e.g. "Hi, thanks for calling Acme Support. How can I help?"). Defaults to "Hello?" if left blank.
  </Step>

  <Step title="Save The Agent">
    Click **Create**. The agent is saved and ready to configure further. Any required voice-instruction or knowledge preparation continues in the background.
  </Step>

  <Step title="Select Knowledge Sources">
    Open **Knowledge Sources** on the agent page and check the instructions and knowledge the agent may use, then click **Save**. A new agent knows only its own instructions until you select sources. See [Knowledge Sources](/phone/agent-config#knowledge-sources).
  </Step>

  <Step title="Assign An Inbound Number">
    Under <Tooltip>**Telephony & Routing**</Tooltip> in the agent settings, assign one or more verified phone numbers. Each number can only be assigned to one agent. For BYOC numbers, see [SIP Integration](/phone/sip-integration).
  </Step>

  <Step title="Make A Test Call">
    Wait for required preparation to complete, then choose **Test → Talk via web** to call the agent directly from your browser. Verify the agent answers, follows instructions, and behaves as expected.
  </Step>
</Steps>

<Info>
  Agents are created without purchasing a separate phone number. Assign a verified number from **[Settings → Phone Numbers](https://platform.open.cx/settings/phone-numbers)**, or use SIP trunking to route calls from your own carrier.
</Info>

## Test Calls

Choose **Test → Talk via web** on the agent page under **[Channels → Phone → Agents](https://platform.open.cx/channels/phone/agents)**. This calls the agent directly from your browser — no phone number needed.

A loading indicator inside **Test** means your agent is being prepared. Hover over
the button or focus it with the keyboard for an explanation. Testing becomes
available when everything required by your saved settings is ready, even if you
reload the page. See [Saving and preparation](/phone/agent-config#saving-and-preparation).

Test calls help verify:

* The agent answers and speaks the first message
* Instructions are followed correctly
* The selected knowledge sources are used
* Transfer destinations work

A browser test does not validate a phone number, caller ID, or carrier route. Before going live, place a real inbound call and an outbound call if you will use both. Verify transfers and [recording settings](/phone/recordings-and-transcripts) separately. See [Numbers and routing](/phone/numbers-and-routing).

## Related Documentation

<CardGroup>
  <Card title="Agent Configuration" icon="sliders" href="/phone/agent-config">
    Voice, flow builder, knowledge sources, actions, and transfers.
  </Card>

  <Card title="Inbound Calls" icon="phone-arrow-down-left" href="/phone/inbound-calls">
    How calls are routed to agents and what happens during a call.
  </Card>

  <Card title="SIP Integration" icon="server" href="/phone/sip-integration">
    Bring your own carrier with SIP trunks.
  </Card>
</CardGroup>


# Phone follow-up workflows and callbacks
Source: https://docs.open.cx/phone/follow-up-workflows

Build outcome-based WhatsApp follow-ups, schedule a one-time AI callback, and pass call details to CRM automation with explicit result checks.

Use separate workflows to start calls and react to their results. Start with a tested [outbound agent](/phone/outbound-calls), permission to edit and activate workflows, and the [Call Finished fields](/phone/call-outcomes) available in your workspace.

## No answer, busy, or voicemail → WhatsApp

You need a connected WhatsApp number, an approved template, and an OpenCX contact with a phone number.

<Steps>
  <Step title="Filter the finished call">
    Create a workflow with **Call Finished**. Add conditions requiring **Direction = Outbound** and **Disposition** equal to `no_answer`, `busy`, or `voicemail`. Keep `unknown`, `failed`, `declined`, and `canceled` on separate branches so their handling is deliberate.
  </Step>

  <Step title="Send the template">
    Add **Send WhatsApp Template**. Set **Contact ID** from `trigger.call.ticket.contact.id`, choose your sending **Phone Number** and **WhatsApp Template**, and fill **Template Variables** in placeholder order: header, body, then buttons. Route a missing contact ID to review instead of sending.
  </Step>

  <Step title="Check the action result">
    Branch on the action's **Sent** output. If false, record or surface **Error** for follow-up. Expected send failures can return `sent: false` without failing the whole workflow, so a completed run alone does not prove a message was sent. A successful send returns a **WhatsApp Message ID**; it does not prove delivery or that the recipient read it.
  </Step>

  <Step title="Test and activate">
    Test each branch with a contact you control. Confirm the recipient, template variables, message in the session, and action result. Check other active workflows and sequences so they do not also send the same follow-up for that attempt.
  </Step>
</Steps>

## Schedule one callback at a chosen time

For an individually configured callback, combine **Cron Trigger** with **Make phone call**:

1. Create a separate workflow for the callback and choose **Cron Trigger**.
2. Set **Cron Expression** for the intended date and time. Set **Run Limit** to `1` so the workflow deactivates after its one scheduled fire.
3. Add **Make phone call**. Set **AI Agent**, the customer's **Contact Number** in international format, and **Extra Instructions** explaining the callback purpose.
4. Confirm the next occurrence before activation, then activate the workflow. Configure result handling in a separate **Call Finished** workflow.

For example, `30 14 25 9 *` means September 25 at 14:30 in the schedule's timezone. Cron configuration without an explicit timezone uses **UTC**; do not assume the browser or customer's local timezone. Convert the agreed customer time before entering the expression. This expression has no year: if the date has passed, its next occurrence is the following year. Always confirm the upcoming occurrence is the one intended.

**Run Limit counts scheduled fires, not successful answers.** A failed or unanswered call does not automatically re-arm this one-time workflow. Choose an explicit retry policy based on the finished call.

To cancel a callback before it fires, deactivate its workflow. To reschedule a pending callback, deactivate it, change the schedule, then reactivate it after checking the new time. Deactivation does not stop a call that has already started. For another callback after the one-shot workflow has fired, create a new workflow; editing the old schedule does not reset its fired count.

For many customers with changing appointment times, keep the schedule and cancellation state in your CRM or scheduling system and invoke the [Make Outbound Call API](/api-reference/phone/make_outbound_call) when each callback is due. Store the returned session reference with the appointment. This is a configured integration; OpenCX does not infer a callback appointment from call feedback alone.

## Delays and session follow-ups

A **Wait** step pauses a workflow for an elapsed duration and supports up to **30 days** per step. It is useful for a relative delay, but has no customer appointment date/time field. A session's scheduled AI follow-up resumes session handling; scheduling one does not itself guarantee an outbound phone dial. Add an explicit **Make phone call** step in the flow that should dial.

Avoid sending every failed callback straight back into the same call-starting flow. Store attempt limits and stop conditions in the system managing the journey so a no-answer result cannot create an endless retry loop.

## Log the result in your CRM

Use **Call Finished** to send the call ID, session ID, contact reference, outcome, disposition, and end time to your CRM automation. Configure the task or note creation explicitly. Connecting a CRM alone does not create a callback task for every call.

For **Send Webhook**, set the receiver URL, HTTP method, required authentication headers, and body fields. Check its **Is Success** and **Status Code** outputs. Your receiving integration must match the CRM contact and handle repeated delivery. See [HubSpot phone tasks and notes](/integrations/hubspot/channels/phone#callback-tasks-and-call-notes) for field mapping and verification.

## Verify the journey

| Scenario | Expected check |
| - | - |
| Human answers | No no-answer WhatsApp message is sent. |
| No answer / busy / voicemail | The intended branch runs once and records its result. |
| Unknown answer type | A deliberate fallback handles it. |
| Missing phone or rejected template | The failed send is visible through **Sent** and **Error**. |
| Callback due | One call-starting run occurs at the agreed time; its result is handled separately. |
| Callback canceled or moved | The old pending schedule does not dial. |
| CRM receives the result twice | It updates or reuses the saved activity instead of creating duplicates. |
| Final summary is delayed | The outcome is retained and summary enrichment waits for available text. |

## Skip a sequence call after a reply

A contact's reply exits them from a sequence. Use **Skip Sequence Step** before **Continue Sequence for Contact** to omit their next pending call while retaining their remaining WhatsApp and email outreach. The action works across sequences and supports all three channels.

You need permission to edit and activate workflows. API and MCP callers need `sequences:write`. Start with a **Sequence Replied** trigger and a condition that identifies “cannot talk now” replies.

1. Add **Skip Sequence Step**. Set **Sequence** to `{{trigger.sequence.id}}` and **Contact ID** to `{{trigger.contact.id}}`.
2. Set **Skip mode** to **Next pending step of a channel**, **Channel** to **Phone**, and **Reason** to `Customer cannot talk now`.
3. Continue only when its **Outcome** is `skipped` or `already_skipped`. For `dispatch_in_progress`, wait for that attempt's outcome before retrying. Other outcomes identify why nothing was skipped.
4. Add **Continue Sequence for Contact**, using the same sequence and contact references. Check its **Resumed** output; `nothing_to_continue` means no pending outreach remains.

Example action inputs after naming the first action `skipPhone`:

```json theme={"dark"}
{
  "sequenceId": "{{trigger.sequence.id}}",
  "contactId": "{{trigger.contact.id}}",
  "mode": "next_channel",
  "channel": "voice",
  "reason": "Customer cannot talk now"
}
```

The continuation action uses:

```json theme={"dark"}
{
  "sequenceId": "{{trigger.sequence.id}}",
  "contactId": "{{trigger.contact.id}}"
}
```

**Channel** appears only for the channel mode. Choose **A specific step** to show the selected sequence's **Step** picker; it stores a zero-based index. Sequence, contact, mode, channel, step index, and reason support workflow references. When the sequence is supplied dynamically, reference the intended step index too.

Changing **Sequence** clears a previously selected step. Choose the step again before saving. **Save** requires **Step** for **A specific step**, and **Channel** for **Next pending step of a channel**; references are accepted and resolved when the workflow runs.

Skipping preserves the original waiting time. A 30-minute wait before the omitted call plus a 60-minute wait before the next email remains a 90-minute gap. For a reply-exited contact, those waits start when **Continue Sequence for Contact** runs. Sending windows can push the schedule later. The skip alone leaves exited contacts exited and parked contacts parked; it never revives a completed, removed, or suppressed enrollment.

Review the contact's sequence journey for **Skipped**, the reason, and its timestamp. Workflow and operator attribution are retained in [contact events](/api-reference/sequences/get-contact-events). See the [skip operation](/api-reference/sequences/skip-step) for the full result and retry contract.


# Human phone calling and transfers
Source: https://docs.open.cx/phone/human-calling

Receive calls in the dashboard, dial customers, transfer with a private consultation, add participants, and manage availability and wrap-up.

Your team can answer calls and dial customers from the dashboard. Human calling must be available in your workspace, and the number must have a working [inbound or outbound route](/phone/numbers-and-routing).

When you answer, start, or rejoin a customer call, the inbox opens that call's session automatically. You can browse other sessions while staying on the call.

## Get ready to answer

1. Open the dashboard and allow microphone access in your browser.
2. Set your agent availability to available and turn on **Available for calls** in the sidebar user menu.
3. Confirm that the inbound number is unassigned to AI, or that the AI agent has a **Team** transfer destination assigned.
4. Place a test call and accept the incoming-call prompt. Check audio in both directions.

Callers who speak another language can be served by an [interpreter](/phone/live-interpretation) bound to the number or team; it joins the call when you accept and translates both ways.

Teammates already on a call, unavailable for calls, or in wrap-up are excluded from new rings. Chat session capacity limits do not affect phone availability. For a team destination, OpenCX first considers eligible members of that team. With telephony pacing off, an empty pool can fall back to available teammates across the workspace. With [team telephony pacing](/phone/call-answering#team-queues-and-telephony-pacing) on, calls wait for that team and only one teammate is offered each call at a time.

For a direct inbound human call, no eligible teammates or an unanswered ring results in a missed call and the caller's line ends. For an AI-to-team handoff, no eligible teammate can leave the AI handling the call. Test both cases when writing the agent's handoff instructions; do not assume automatic voicemail or callback scheduling. To offer voicemail from an IVR, configure [Record Voicemail](/phone/call-flows#voicemail-for-a-team) with a receiving team and callback number.

For direct inbound calls to your team, choosing **Accept** reserves the call while your browser connects. Connected duration starts once the phone connection is confirmed. If the line ends before that connection is established, the attempt is recorded as unanswered instead of completed. Reopening an ended call does not reconnect the caller; use the call-back control to start a new attempt.

## Make an outbound call

Use the dashboard dialer to select a verified caller number and enter the customer's international phone number. To return a call from an existing phone session, use its call-back control; the new attempt is kept with that session. This starts a call immediately. It does not schedule a later callback.

Starting a call from an existing session requires **Sessions** write access or **Voice settings** write access. Starting a new session requires **Create sessions** write access or **Voice settings** write access.

## Choose an outbound caller ID

In the dashboard dialer, open **Make the call from** to choose a verified caller ID. Search by name or phone number, including a partial number or a pasted number with spaces and punctuation. You can also scroll through the list and use the arrow keys and Enter to select a result. Press Escape to close the picker without changing the selected number.

## Hold and transfer

Use **Hold** to pause the customer leg and **Resume** to return. Use **Transfer** to select a destination. During a consultation transfer, the customer stays on hold while you speak privately with the destination. Choose **Complete** to hand over, or **Cancel** to return to the customer. If the destination does not answer, cancel the ring and resume the call.

The invited teammate can choose **Leave call** to leave a consultation before the transfer is completed. The customer stays with the original agent, who can resume the call or choose another destination. An unfinished transfer on an ended call does not keep the invited teammate busy; their availability and wrap-up settings still apply.

A consultation transfer and a conference serve different purposes: completing a transfer hands the customer over; adding a participant keeps people together on the call.

## Add participants

On a connected call, the host can choose **Add participant** and invite an available teammate or dial an external phone number. External dialing uses a verified caller number. Adding participants requires **Sessions** write access.

**Participants** shows connected people and pending invites. The host can withdraw an invite or remove a participant. If removal is interrupted, OpenCX retries it automatically. A teammate with a pending removal cannot rejoin by refreshing the page. An invited teammate can leave without ending the call for everyone. Muting a participant for yourself only changes what you hear.

The call timeline records participant changes. Recording and live transcripts, when enabled, continue across the call; see [Recordings and transcripts](/phone/recordings-and-transcripts).

## Wrap up and missed calls

Admins configure **Wrap-up time** in **[Settings → Voice & Telephony](https://platform.open.cx/settings/telephony)**. A team can override this duration under **Settings → Teams**. While wrapping up, you do not receive new call rings from any team. Use **I'm ready** to finish early or add a minute if needed.

Review missed calls in the inbox and decide whether to call back or use another channel. A missed human call is not automatically an AI outbound **Call Finished** workflow event. Validate the event source for the specific automation you configure.

## Linking callers to your own customer profile

Most phone calls arrive as a number. Two settings turn that number into the customer your agents already know.

**Contact profile link** (Settings → Workspace) adds a button to the session panel, the in-call bar and the incoming-call popup that opens the customer in your own admin. The URL is a template over the contact:

```text theme={"dark"}
https://admin.example.com/users?phone={{contact.phone_number}}
```

Placeholders: `{{contact.phone_number}}`, `{{contact.email}}` and `{{contact.custom_data.<key>}}` for any contact attribute. Values are URL-encoded; when a contact has no value for a placeholder the button is not shown. On the incoming-call popup the button follows the caller-number privacy setting, so a hidden number never leaks through the link.

**Identity on incoming calls.** When a call rings your agents, the caller's contact is matched against the connected customer systems (ticketing system, then the CRM connections) and the contact's name and email are filled in from the match. The lookup runs alongside the ring and never delays it.

If your customer data lives somewhere else, a workflow can do the lookup. The `Phone call started` trigger fires for every incoming call with the contact on `trigger.call.ticket.contact`, after the built-in matching has finished:

1. Add an action that finds a customer by phone number in your system.
2. Create a workflow on the `Phone call started` trigger that calls that action with `{{trigger.call.ticket.contact.phone_number}}`.
3. Follow it with an **Update contact** step that sets the name and stores your customer id as a contact attribute, for example `admin_user_id`.
4. Point the contact profile link at that attribute: `https://admin.example.com/users/{{contact.custom_data.admin_user_id}}`.

From the next call on, the popup and the session panel open the right profile in one click.

## Organization selection and page refresh

Incoming calls, transfer requests, and conference invites ring in dashboard tabs open to the organization receiving the call. If you work in multiple organizations, open a tab for each organization where you want to receive calls and set your call availability there.

Refreshing the page during a customer call briefly interrupts your audio. The dashboard reconnects to the same active call if the page returns within 30 seconds. Keep the same organization selected and allow microphone access. If no agent reconnects, the call ends after this grace period. Choosing **End call** still hangs up immediately.


# Human phone agent guide
Source: https://docs.open.cx/phone/human-phone-agent

Find the current human calling guide, including setup, supported calling behavior, and links to related phone documentation.

The current guide is **[Human calling](/phone/human-calling)**. Start there for setup and operating instructions.

For the complete guide list, see [Phone overview](/phone/introduction).


# Inbound Calls
Source: https://docs.open.cx/phone/inbound-calls

How inbound calls are routed to AI phone agents — call flow, session matching, silence detection, call endings, and recording.

Use **[Create Phone Agent](/phone/create-agent)** first if you haven't set up an agent yet.

<Tip>
  **Inbound Calls** covers what happens when a customer calls your number. For agent settings, see [Agent Configuration](/phone/agent-config). For outbound calls, see [Outbound Calls](/phone/outbound-calls).
</Tip>

## Path Of A Call

```mermaid theme={"dark"}
flowchart LR
  A([Caller]) --> B[Phone number]
  B --> C[Route to agent]
  C --> D[AI answers]
  D --> E[AI handles the call]
  E --> F([End or transfer])

  style A fill:#1a5c20,color:#fff,stroke:#267a2e
  style F fill:#1a5c20,color:#fff,stroke:#267a2e
```

<Steps>
  <Step title="Customer Calls Your Number">
    The customer dials a phone number assigned to an AI agent.
  </Step>

  <Step title="Routed To The Correct Agent">
    **OpenCX** matches the dialed number to its assigned agent. For SIP calls, a valid `X-OPENCX-AGENT-ID` header takes precedence over number assignment. A recognized workspace with no resolved AI agent can route the call to teammates. See [Numbers and routing](/phone/numbers-and-routing).
  </Step>

  <Step title="AI Speaks First Message">
    The agent greets the caller with its configured first message (e.g. "Thanks for calling. How can I help?").
  </Step>

  <Step title="Handle the call">
    The AI listens, responds using its instructions and knowledge, and can trigger actions or workflows during the call. The full transcript is recorded in the [inbox](https://platform.open.cx/inbox).
  </Step>

  <Step title="End Or Transfer">
    The call ends when the AI says goodbye, the caller hangs up, or the AI transfers the call to a human agent or external number.
  </Step>
</Steps>

For calls your team should answer directly, use [Human calling](/phone/human-calling) to configure availability and understand missed calls.

## Calls routed to your team

For customer calls answered by human agents, configure [call answering and ringing](/phone/call-answering) to connect prepared dashboards automatically after a delay and ring a percentage of available agents. The same settings apply when an AI phone agent hands a call to your team.

## Call Behavior

Includes <Tooltip>silence detection</Tooltip>, end-call behavior, and interruption handling.

| Behavior | Detail |
| - | - |
| **Silence detection** | If the caller is silent, the agent prompts "Are you still there?" up to **2 times**. After that, it ends the call. |
| **Hold** | When the caller asks for a moment or needs time to find something, the agent tells them to take their time and waits about a minute before checking in. |
| **End call** | The AI says goodbye and waits for the speech to finish. If the caller **speaks during the goodbye**, the AI re-engages instead of hanging up. If the caller only says goodbye or thanks back, the AI hangs up without another farewell. |
| **Interruption** | Callers can interrupt the AI mid-sentence by default. The AI stops speaking and listens. |
| **Pauses mid-answer** | If the caller pauses partway through a phone or reference number, or trails off mid-sentence, the AI says a soft "Mhm" and keeps listening instead of replying. A caller who has finished still gets a full reply. |
| **Audio quality** | The AI only responds to clear speech. Background noise, static, or unintelligible audio is ignored to avoid false triggers. |

## Good To Know

<AccordionGroup>
  <Accordion title="Session Matching" icon="link">
    Contact identity is matched using the caller's phone number. Contact matching does not mean every new call reuses one session. Review the call attempt and session together, especially after callbacks.
  </Accordion>

  <Accordion title="Transcripts And Recording" icon="microphone">
    AI calls produce transcript messages during the session. Audio recording is a separate agent setting. For human calls, enable **Live transcripts** in **Settings → Voice & Telephony** for speaker-labeled messages during supported calls. Post-call summary processing can use an available recording when live text is unavailable.

    See [Recordings and transcripts](/phone/recordings-and-transcripts) for permissions, settings, and timing.
  </Accordion>

  <Accordion title="DTMF Tones" icon="hashtag">
    The agent can detect keypad tones (<Tooltip>DTMF</Tooltip>) pressed by the caller during the call.
  </Accordion>

  <Accordion title="Call Transfers" icon="arrow-right-arrow-left">
    When configured, the AI can transfer to a team, phone number, or SIP destination. A Custom destination ends the call. Transfer destinations must be assigned to the agent in **[Channels → Phone → Agents](https://platform.open.cx/channels/phone/agents)**.
  </Accordion>

  <Accordion title="Adding Participants To A Call" icon="users">
    Once a teammate has taken a call in the [inbox](https://platform.open.cx/inbox), they can bring more people onto it from the call controls with **Add participant**:

    * **A teammate** — pick anyone who is online and available for calls. Their dashboard rings, and they join the call as soon as they accept.
    * **A phone number** — dial an external number from one of your verified phone numbers. The line joins the call when it picks up.

    Everyone on the call hears each other. **Participants** shows who is on the line and who is still being rung. Anyone on the call can mute a participant for themselves: that participant goes silent in your headset only, everyone else keeps hearing them, and you can unmute them at any time. The teammate who took the call is the host: only they can add people, remove a participant, or withdraw an invite that is still ringing. Invited teammates can leave whenever they want without ending the call for anyone else.

    Recording and the live transcript keep covering the whole call, and the call timeline in the inbox shows who joined, who left, and who was removed. Adding participants needs the **Sessions** write permission.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Agent Configuration" icon="sliders" href="/phone/agent-config">
    Voice, instructions, knowledge, actions, and transfers.
  </Card>

  <Card title="Outbound Calls" icon="phone-arrow-up-right" href="/phone/outbound-calls">
    Make AI-powered outbound calls.
  </Card>

  <Card title="SIP Integration" icon="server" href="/phone/sip-integration">
    Route inbound calls from your own carrier.
  </Card>
</CardGroup>


# Phone and telephony overview
Source: https://docs.open.cx/phone/introduction

Set up AI and human phone support, route your numbers, review calls, and configure outcome-based follow-ups across WhatsApp and your CRM.

Use OpenCX for Classical IVR, AI calls and human calling from the dashboard. Your phone numbers, agent configuration, team availability, and workflows determine the journey a caller receives.

## Start with your calling setup

<Steps>
  <Step title="Connect and route your number">
    Choose a hosted number or bring your own carrier, verify the number, and decide whether AI or teammates should answer. Start with [Numbers and routing](/phone/numbers-and-routing); use [SIP setup](/phone/sip-integration) for your own carrier.
  </Step>

  <Step title="Prepare the people or AI that will answer">
    [Create a phone agent](/phone/create-agent) and configure its instructions and transfer destinations, build recorded keypad menus with [Classical IVR](/phone/call-flows), or set up [human calling](/phone/human-calling) and team availability.
  </Step>

  <Step title="Test each direction">
    Test [inbound calls](/phone/inbound-calls), [outbound calls](/phone/outbound-calls), and transfers with real phones. Browser test calls help check the agent, but do not verify your carrier routes.
  </Step>

  <Step title="Review and automate">
    Review [recordings and transcripts](/phone/recordings-and-transcripts), understand [call outcomes](/phone/call-outcomes), and configure [follow-up workflows](/phone/follow-up-workflows).
  </Step>
</Steps>

## Find the right guide

| Task | Guide |
| - | - |
| Choose numbers, caller ID, and who answers | [Numbers and routing](/phone/numbers-and-routing) |
| Set voice, language, instructions, tools, and transfers | [Agent configuration](/phone/agent-config) |
| Answer, dial, consult, transfer, or add participants | [Human calling](/phone/human-calling) |
| Talk to callers in another language through your team | [Live interpretation](/phone/live-interpretation) |
| Distinguish busy, no answer, voicemail, and unknown | [Call outcomes](/phone/call-outcomes) |
| Send WhatsApp or schedule a callback | [Follow-up workflows](/phone/follow-up-workflows) |
| Find recordings, transcripts, and summaries | [Recordings and transcripts](/phone/recordings-and-transcripts) |
| Diagnose a failed call or missing follow-up | [Troubleshooting](/phone/troubleshooting) |

## Connect customer systems

* [Zendesk telephony](/integrations/zendesk/telephony): forward calls into OpenCX and transfer back to your agent workspace.
* [HubSpot phone support](/integrations/hubspot/channels/phone): configure handoff tickets and call task/note automation.
* [Phone API](/api-reference/phone/make_outbound_call): initiate AI outbound calls from your application.
* [Webhook events](/api-reference/webhooks/types): send call results to an external receiver.

A connected integration, a call outcome, and a scheduled follow-up each serve a different part of the journey. Configure the actions that should send messages, dial callbacks, or create CRM activities, then verify them with a test contact.


# Live interpretation for team phone calls
Source: https://docs.open.cx/phone/live-interpretation

Set up an interpreter so callers and your team each speak their own language on a live phone call. Use when a number or team serves callers in a language the team does not speak.

An interpreter puts your own team on the line with a caller who speaks another language and translates both ways while the call runs. Unlike an AI agent, it has no instructions, knowledge, or tools: your teammate answers the call, and the interpreter only carries what each side says into the other language.

## Prerequisites

* **Voice settings** write access to create or change an interpreter. Read access is enough to see the list.
* [Human calling](/phone/human-calling) available in your workspace, with teammates set to **Available for calls**.
* A **verified phone number** under **[Settings → Phone Numbers](https://platform.open.cx/settings/phone-numbers)** if callers dial in, or a team if calls reach your team from the app or a transfer.
* Interpreters are rolling out gradually. If **Select Interpreter** is not offered in your workspace yet, ask your OpenCX contact to enable it.

## Create an interpreter

1. Open **[Channels → Phone → Agents](https://platform.open.cx/channels/phone/agents)** and choose **New Phone Agent**.
2. Pick **Select Interpreter**. The **AI Agent** option is the regular agent that answers and resolves calls on its own.
3. Fill in the form and save:

| Section | Field | What it does |
| - | - | - |
| Basics | **Name** | How the interpreter appears in the agents list. |
| Basics | **Phone number** | Inbound number the interpreter answers for. Optional when the interpreter serves a team only. |
| Basics | **Team** | Team whose calls get interpreted. Inbound calls to the number ring this team; with no team, they ring everyone available. |
| Languages | **Caller speaks** | The language callers use on this number or team. |
| Languages | **Your team speaks** | The language your teammates hear and speak. |
| Voices | **Caller-facing voice**, **Team-facing voice** | The voice each side hears. Leave empty for the default voice of that language. |
| Voices | **Caller's own voice** | How loud your teammates hear the caller's original voice underneath the translation, from silent to full. Lower it when the original competes with the interpreter; the translation always plays at full volume. |
| Glossary | **Terms to keep as they are** | Product names, plan names, and codes that must never be translated, one per line. |

A number and a team can each have one interpreter. Saved interpreters appear under **Interpreters** on the agents page, where you can edit or delete them.

## How an interpreted call works

* A call to the interpreter's number, or a call that reaches its team, rings your teammates as any other team call. The interpreter joins the moment a teammate accepts.
* Interpretation is consecutive: each side speaks, pauses, and then hears the translation. Short sentences and a brief pause after each one give the best results.
* Only speech in each side's configured language is interpreted. Words in another language, background voices, and the sound of the translation itself are left out, so neither side hears its own words translated back.
* The caller hears only the interpreter's voice in their language; your teammate's own voice is not played to the caller. Your teammate hears the caller's original voice and the interpreter's translation.
* Hold, transfer, participants, wrap-up, and availability work as described in [Human calling](/phone/human-calling).

## Transcripts and recordings

Every turn lands in the session as a transcript message in the language the other side heard, with **Show original message** revealing what was actually said. Interpreted calls do not need the **Live transcripts** setting; the interpreter writes the transcript itself. Recording follows the same rules as other team calls, see [Recordings and transcripts](/phone/recordings-and-transcripts).

## Limitations and troubleshooting

* If a translation cannot be produced for a sentence, that sentence is skipped and the original still appears in the transcript. The call continues.
* **No interpreter on the call.** Check that the dialled number or the ringing team is bound to the interpreter, and that the teammate accepted the call from the dashboard. Calls answered on a SIP phone or an external destination are not interpreted.
* **Caller hears nothing.** Ask your teammate to pause after each sentence; the translation plays once the sentence is complete.


# Phone numbers and routing
Source: https://docs.open.cx/phone/numbers-and-routing

Choose a hosted number or your own carrier, route inbound calls to IVR, AI or teammates, and configure the caller number for outbound calls.

Start in **[Settings → Phone Numbers](https://platform.open.cx/settings/phone-numbers)**. A number's verification, inbound assignment, and outbound route are separate parts of setup. Test each direction you intend to use.

## Choose a number setup

| Setup | What to configure |
| - | - |
| Hosted number | Use a verified hosted number in your workspace; choose its inbound destination and outbound caller use. |
| Your own carrier (BYOC) | Verify your number and configure the required inbound and outbound trunks in **[Settings → SIP](https://platform.open.cx/settings/sip)**. See [SIP setup](/phone/sip-integration). |
| Existing number moving to OpenCX | Contact [support](mailto:support@open.cx) to arrange the move before changing your existing service. Verifying a number does not move its inbound traffic. |

Use international format, for example `+14155551234`. A verified number confirms that you can use it; it does not by itself configure your carrier's routing or permission to place calls to every destination.

## Route incoming calls

1. Create an agent in **[Channels → Phone → Agents](https://platform.open.cx/channels/phone/agents)** if AI should answer.
2. Open the agent's **Telephony & Routing** settings and assign the inbound number. A number can have only one inbound destination: an AI phone agent or a Classical IVR. Unassign its existing destination before switching between those types.
3. Check **Inbound Agent** beside the number in **Settings → Phone Numbers**.
4. Call that number from a real phone and verify who answers.

For recorded keypad menus, enable **Classical IVR** in **Settings → Voice & Telephony**, then assign the number from **Channels → Phone → Classical IVR → Workflows**. **Settings → Phone Numbers → Inbound destination** shows the assigned IVR or agent. See [Classical IVR setup](/phone/call-flows).

For supported inbound routes, an **Unassigned** number rings eligible teammates in the dashboard. Keep a teammate online and **Available for calls** when testing this path. See [Human calling](/phone/human-calling) for eligibility and missed calls.

When Classical IVR is enabled, calls to a number assigned to an IVR run that workflow first. For calls without an active IVR assignment, a valid `X-OPENCX-AGENT-ID` header for your workspace takes precedence. Otherwise, OpenCX looks up the agent assigned to the dialed number. If no agent is resolved for a recognized workspace, the call can enter the human-answering path. Do not rely on an unspecified workspace default AI agent; assign the number or send the header explicitly.

## Configure outbound calls

**AI calls:** open the agent's **Telephony & Routing** settings and select its outbound caller number or outbound SIP trunk. The agent's inbound number assignment alone is not proof that outbound calling works.

**Human calls:** choose a verified caller number in the dashboard dialer. OpenCX resolves an outbound route for that number, using a matching configured number route, an owning agent's route, or the workspace's hosted route where available. External numbers need a valid outbound route. See [Human calling](/phone/human-calling).

Your carrier must accept the caller identity and destination on that route. Test the caller ID on the receiving phone; the same displayed caller number does not prove that an AI call and a human call used the same route.

## Access and verification

Changing phone configuration requires **Voice settings** write access. API callers need `phone:write` to [start an AI outbound call](/api-reference/phone/make_outbound_call).

Before opening the line to customers, verify:

* A real inbound call reaches the intended IVR, AI agent or teammate.
* An AI outbound call connects and displays the intended caller ID.
* A human outbound call works if your team will use the dialer.
* Each transfer destination answers, and the team knows what to do if it cannot.
* The session contains the expected call record and, when enabled, recording.

A browser **Test Call** checks the agent experience. It does not verify a phone number's carrier route. For failed real calls, use [Phone troubleshooting](/phone/troubleshooting).


# Outbound Calls
Source: https://docs.open.cx/phone/outbound-calls

Make AI-powered outbound calls from the dashboard, via API, or through automated workflows.

<Tip>
  For agent setup, see [Create Phone Agent](/phone/create-agent). For caller number, trunk, and transfer settings, see [Agent Configuration](/phone/agent-config).
</Tip>

## Prerequisites

Before making outbound calls, the agent must have an **outbound caller number** configured:

* **Hosted number** — select a verified number from **[Settings → Phone Numbers](https://platform.open.cx/settings/phone-numbers)**.
* **Custom <Tooltip href="/phone/sip-integration">SIP</Tooltip> trunk** — configure an outbound trunk under **[Settings → SIP](https://platform.open.cx/settings/sip)** and assign it to the agent.

Set this under **Telephony & Routing** in **[Channels → Phone → Agents](https://platform.open.cx/channels/phone/agents)**.

## How To Make Outbound Calls

<Tabs>
  <Tab title="From the dashboard">
    <Steps>
      <Step title="Open The Agent">
        Go to **[Channels → Phone → Agents](https://platform.open.cx/channels/phone/agents)** and open the agent that should place the call.
      </Step>

      <Step title="Start The Call Flow">
        Click **Test**, then select **Make phone call**.
      </Step>

      <Step title="Enter The Destination Number">
        Enter the destination number in <Tooltip>E.164 format</Tooltip>, then click **Call**.
      </Step>

      <Step title="Let The Call Connect">
        OpenCX starts the outbound call immediately using the outbound caller number or SIP trunk assigned to that agent.
      </Step>
    </Steps>

    ### Quick Validation

    | Check | What to confirm |
    | - | - |
    | Answer the call | Call your own phone or a teammate first. |
    | Caller ID | The displayed number matches the number or trunk assigned to the agent. |
    | Review path | The session appears in the [inbox](https://platform.open.cx/inbox). |
  </Tab>

  <Tab title="Via API">
    Use this endpoint for one-time call attempts. It does not queue requests for later execution. For scheduled or bulk calling, use the [Sequences API](/api-reference/sequences/index).

    <Steps>
      <Step title="Prepare Access">
        Use the [Make Outbound Call](/api-reference/phone/make_outbound_call) endpoint with an API key that has <Tooltip>`phone:write`</Tooltip>.
      </Step>

      <Step title="Choose The Agent And Contact">
        Send the agent ID as <Tooltip>`phoneAgentId`</Tooltip> and pass the destination as <Tooltip>`contact.phoneNumber` or `contact.id`</Tooltip>.
      </Step>

      <Step title="Send The Request">
        Post the payload to request a call immediately.

        ```json theme={"dark"}
        {
          "phoneAgentId": "6ef668ec-06cc-4df1-8df0-a56689bd0473",
          "contact": {
            "phoneNumber": "+14155551234"
          }
        }
        ```
      </Step>

      <Step title="Track The Result">
        Check the HTTP status and response body for errors, then confirm the new call session appears in the [inbox](https://platform.open.cx/inbox). An accepted request does not mean the recipient answered. See [Make Outbound Call](/api-reference/phone/make_outbound_call) for rejected-request handling.
      </Step>
    </Steps>

    ### Quick Validation

    | Check | What to confirm |
    | - | - |
    | Safe destination | Start with a number you can answer yourself. |
    | API response | The request succeeds and the phone rings. |
    | Review path | The transcript starts populating in the [inbox](https://platform.open.cx/inbox). |
  </Tab>

  <Tab title="Via workflows">
    <Steps>
      <Step title="Open Or Create A Workflow">
        Go to your workflow builder and choose the trigger that should launch the phone call, such as a form submission, scheduled run, or external event.
      </Step>

      <Step title="Add The Call Action">
        Add the **Make phone call** action to the workflow.
      </Step>

      <Step title="Fill The Required Fields">
        Set **AI Agent**, **Contact Number**, and **Extra Instructions**. Use the extra instructions field for call-specific context the agent should follow for this run.
      </Step>

      <Step title="Handle The Result">
        Add cleanup steps after the call action, such as clearing a contact's “call in progress” attribute. Branch on **Status** to choose the follow-up. See [Workflow call results](#workflow-call-results) for the returned values and timeout behavior.
      </Step>

      <Step title="Activate The Workflow">
        Save and activate the workflow so future runs can place calls automatically.
      </Step>
    </Steps>

    ### Quick Validation

    | Check | What to confirm |
    | - | - |
    | Safe trigger | Trigger the workflow once with a safe test input. |
    | Reachability | Use a number you can answer. |
    | Review path | The run completes and the session appears in the [inbox](https://platform.open.cx/inbox). |
  </Tab>
</Tabs>

## Follow Up On Call Outcomes

After pickup, the agent starts its opening without waiting for the recipient to speak. The agent continues listening and transcribing during the opening so voicemail detection can run in the background. Incoming speech does not cut off the protected opening. If voicemail is detected, the agent stops speaking and ends the call; part of the opening may already have played. An inconclusive check does not interrupt the call.

Use **Call Finished** and **Call → Disposition** (`trigger.call.disposition`) to distinguish no answer, busy, voicemail, and other results. The trigger covers AI outbound attempts, including failures before the agent speaks. See [Call lifecycle and outcomes](/phone/call-outcomes) for the full field reference, uncertain results, and summary timing.

Follow [Phone follow-up workflows](/phone/follow-up-workflows) to send a WhatsApp template, configure a one-time callback, or log results in your CRM. These actions require explicit workflow configuration.

### Workflow Call Results

**Make phone call** waits up to **30 minutes** for a call result. Use its **Status** output to decide what happens next:

| Status | Meaning |
| - | - |
| `completed` | The call ended normally. This alone does not prove a person answered. |
| `transferred` | The call was transferred. |
| `unanswered` | The attempt ended without an answer, or was classified as busy, declined, canceled, or voicemail. |
| `failed` | The attempt failed, including failures before the agent joined. |
| `timeout` | No final call result was available within 30 minutes. |

These results let the workflow continue to later steps, including contact cleanup. A `timeout` does not hang up the call. Missing agents or sessions and other runtime errors can still fail the step.

**Summary** and **Recording URL** contain the available session summary and recording link. Either may be empty when the step finishes; an empty output does not fail the step. Recording links expire after one hour.

<Note>
  Agents using the organization knowledge base return `success` immediately without waiting for the call to finish. Use **Call Finished** for their completion handling. Use **Call → Disposition** whenever you need detailed answer evidence.
</Note>

<Warning>
  **Update existing outcome branches.** If a workflow checks this action's **Status** for `success` after waiting for the call, replace that condition with the appropriate outcome above and handle `timeout`. The immediate `success` response for agents using the organization knowledge base is unchanged.
</Warning>

## Common Outbound Call Mistakes

<Warning>
  Most failed first tests come from three issues: the destination number is not in `E.164` format, the agent does not have an outbound caller number or SIP trunk assigned, or the team tests with a number nobody can answer.
</Warning>

## Questions Teams Usually Ask Before Going Live

<AccordionGroup>
  <Accordion title="How do I confirm the right number is being shown?" icon="phone">
    The recipient sees the hosted outbound number or SIP trunk caller ID assigned to the agent in **[Channels → Phone → Agents](https://platform.open.cx/channels/phone/agents)**. Test with a phone you can answer before calling customers.
  </Accordion>

  <Accordion title="Where do I review the call afterwards?" icon="inbox">
    Open the [inbox](https://platform.open.cx/inbox) to review the transcript and call record after the call starts.
  </Accordion>

  <Accordion title="What should I check if the call does not start?" icon="triangle-exclamation">
    First confirm the number is in `E.164` format. Then open **[Channels → Phone → Agents](https://platform.open.cx/channels/phone/agents)** and verify **Telephony & Routing** includes either a hosted outbound caller number or an outbound SIP trunk.
  </Accordion>

  <Accordion title="Can the agent transfer the call if needed?" icon="arrow-right-arrow-left">
    Yes. If transfer destinations are assigned to the agent, it can transfer the live call during the call. Configure those destinations in **[Channels → Phone → Agents](https://platform.open.cx/channels/phone/agents)**.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Agent Configuration" icon="sliders" href="/phone/agent-config">
    Set outbound caller number and trunk under Telephony & Routing.
  </Card>

  <Card title="Create Phone Agent" icon="plus" href="/phone/create-agent">
    Set up the agent before placing live outbound calls.
  </Card>

  <Card title="SIP Integration" icon="server" href="/phone/sip-integration">
    Configure outbound SIP trunks for BYOC.
  </Card>

  <Card title="Phone API" icon="code" href="/api-reference/phone/make_outbound_call">
    Make outbound calls programmatically.
  </Card>
</CardGroup>


# Phone calling guide
Source: https://docs.open.cx/phone/phone-calling

Find the current inbound calls guide, including setup, supported calling behavior, and links to related phone documentation.

The current guide is **[Inbound calls](/phone/inbound-calls)**. Start there for setup and operating instructions.

For the complete guide list, see [Phone overview](/phone/introduction).


# Phone Desk agent workspace
Source: https://docs.open.cx/phone/phone-desk

Set up a focused workspace for human phone agents by hiding the session list while keeping the existing timeline, call controls, notes and session details.

Phone Desk is a focused mode of the existing inbox. It hides the session list and optional views sidebar on the left while keeping the session timeline, notes, call history and right-hand details panel. Existing organizations keep their current inbox unless the mode is enabled.

## Enable Phone Desk mode

1. Open **Settings → Voice & Telephony**. Enable telephony, then turn on **Enable Phone Desk mode**. You need permission to edit voice settings.
2. In the inbox, select **Phone Desk mode** to hide the list. Users with a full-inbox role can select **Show session list** to return to the full inbox. Your selected session stays open.
3. To make this the default for agents, open **Settings → Roles** and choose **Phone Desk** as the role's **Default workspace**. The **Telephony Agent** preset provides a starting set of calling and session permissions; review these before assigning it.

Users whose roles default to Phone Desk have a simplified sidebar without the Companion, Apps and Settings section. **My Profile** remains accessible from the user menu. These agents do not see the **Show session list** switch. Other users keep the normal navigation.

The mode changes presentation, not access permissions. If an agent has multiple roles, every role must select Phone Desk for it to become their default. A legacy role or a role set to Full inbox keeps the normal inbox as their default.

## Work in the familiar inbox

* **Middle:** the existing session timeline, messages, call history, recordings and internal notes.
* **Right:** the existing contact and session details, attributes and inbox widgets. Use the normal session-info button if the panel is collapsed.
* **Availability:** open **Availability** beside the dialer to adjust your status, availability for calls and team availability. These are the same controls available from your user menu.
* **Calls:** when no session is open, the dialer appears in the center of the workspace. With a session open, select **New call** beside the Phone Desk title to leave the current session view and return to the centered dialer. The incoming-call banner, active-call controls and wrap-up strip work as they do in the full inbox.

When you accept a customer call in Phone Desk mode, its session opens automatically. When wrap-up expires or you select **I’m ready**, Phone Desk clears the completed call from your view and returns to the dialer. Extending wrap-up keeps the session open longer. This does not close or delete the session itself, and it will not dismiss another session you opened or a new active call. Users with a full-inbox role can show the list to select another session. On mobile, session details continue to open in the existing details sheet.

With a zero-second wrap-up, the completed call leaves the desk immediately. If you reload during wrap-up, the open session stays in place because the desk can no longer confirm which call the remaining wrap-up belongs to. Select **New call** to return to the dialer.

Switching modes preserves the selected session and does not replace the calling connection. Availability, team membership, business hours, auto-answer and wrap-up settings keep their existing behavior. See [Call answering](/phone/call-answering) and [Human calling](/phone/human-calling).

## Hybrid Inbox: calls and chats

Hybrid Inbox is off by default and is enabled separately from Phone Desk.

1. Open **Settings → Voice & Telephony** and turn on **Enable Hybrid Inbox mode**.
   Changing this setting requires Voice & Telephony write access. Telephony must
   also be enabled for agents to use the workspace.
2. In **Settings → Roles**, create a role using the **Hybrid Agent preset**, or
   grant an existing role **Hybrid Inbox** access and **Inbox** read access.
   The preset includes replying to sessions, starting sessions and editing the
   agent's own profile. Calling keeps its existing prerequisites.
3. Assign the role to the intended teammates, including when adding new people.
   Set the role's **Default workspace** to **Hybrid Inbox** to open it automatically.
   Agents with mixed workspace defaults keep the full inbox as their default.
4. Authorized agents can select **Hybrid Inbox mode** in the inbox toolbar.
   Users with a full-inbox role can return using **Full inbox**. The switch is
   hidden for agents whose roles default to Hybrid Inbox or Phone Desk.

Turning Hybrid Inbox off hides its entry point and prevents direct links from
opening it, even for administrators. Existing role assignments are retained for
later re-enablement; administrators can still see and revoke retained Hybrid Inbox
grants in the role editor while the workspace is off. Removing a user's Hybrid Inbox
or Inbox access also removes access to the workspace. Unavailable links use the
agent's available default workspace: Phone Desk for Phone Desk agents, otherwise
the regular inbox with its existing permissions and saved views. Administrators
can use the mode when it is enabled;
other agents need the explicit Hybrid Inbox permission. In user permission responses,
this permission is named `hybrid-inbox:read`; it does not grant session access or
additional API scopes by itself.

Phone Desk settings, existing role defaults and the regular inbox stay unchanged.

* **Chats** lists non-voice sessions, including chat, email and messaging.
* **Calls** lists phone and web-call sessions. Select **New call** to open the dialer.
* Open sessions are highlighted in orange in both lists. The selected session also has an outline.
* Both tabs show only sessions **Assigned to me**. This does not edit your saved
  inbox views.
* Each channel remembers its selected session while this workspace stays open.
  Reply text and internal-note drafts use the existing session draft storage.
* An incoming call automatically opens its session in **Calls** when it rings,
  including before it is accepted or assigned. Accept and decline controls remain
  available. Select **Chats** to return to your saved chat selection and draft;
  the same call will not repeatedly switch you back.
* When wrap-up expires or you select **I’m ready**, the completed call returns
  automatically to your last selected chat, or the chat list if none was selected.
  Extending wrap-up delays the return. A new call or another session you opened
  is not interrupted.
* **Availability** uses the same status and call-availability controls as the
  regular inbox. Switching tabs does not change availability or assignment capacity.
* **Full inbox** returns to the existing inbox with its saved views and filters.
  This switch is hidden for agents whose roles default to Hybrid Inbox or Phone Desk.

The call list is session history, not a live waiting-call queue. Existing auto-answer,
wrap-up, routing, recording and call controls retain their current behavior.


# Phone support setup
Source: https://docs.open.cx/phone/phone-support

Find the current phone overview guide, including setup, supported calling behavior, and links to related phone documentation.

The current guide is **[Phone overview](/phone/introduction)**. Start there for setup and operating instructions.

For the complete guide list, see [Phone overview](/phone/introduction).


# Phone recordings, transcripts, and summaries
Source: https://docs.open.cx/phone/recordings-and-transcripts

Configure call recording and live team transcripts, find call evidence in the inbox, and understand what is available during and after a call.

Open a phone session in the [inbox](https://platform.open.cx/inbox) to review call attempts, transcript messages, summaries, and available audio. These are separate outputs and may become available at different times.

## AI calls

AI speech and customer speech appear as transcript messages during the session. Audio recording is controlled separately: open the agent in **[Channels → Phone → Agents](https://platform.open.cx/channels/phone/agents)** and enable **Call recording → Record calls**, where that control is available, then save.

A transcript does not prove that audio recording was enabled. If recording was off, enabling it later does not recover audio from past calls. Changes to agent settings require **Voice settings** write access.

## Calls answered by your team

In **[Settings → Voice & Telephony](https://platform.open.cx/settings/telephony)**, use **Live transcripts → Transcribe calls answered by your team live**. Changing this requires **Voice settings** write access.

| Setting | Expected behavior |
| - | - |
| Off | Post-call processing can use an available recording to generate a summary. Recording-derived text is not the same as live, speaker-labeled messages in the session. |
| On | Supported calls answered directly, handed off from AI, or dialed by a teammate receive speaker-labeled transcript messages while the call runs. Post-call processing can use those messages for the summary. |

Calls handled by an [interpreter](/phone/live-interpretation) always receive transcript messages, with each turn shown in the language the other side heard and **Show original message** for what was said. The live transcripts setting does not apply to them.

If a live transcript is unavailable, processing can fall back to a usable recording. If neither usable audio nor transcript exists, a summary may be unavailable. Very short or silent calls may also have no useful text.

For human calls on a number owned by a phone agent, that agent's recording setting also applies to the human dialing path. Check it when live transcription is off and a recording-based summary is expected.

For conferences, recording and transcription cover the ongoing call when enabled; the call timeline separately shows participant joins, leaves, and removals.

## Review after hang-up

1. Open the correct session and select the relevant attempt if there were multiple calls.
2. Review the call result and participant timeline.
3. Check transcript messages and the session summary. Allow post-call processing to finish.
4. Play or download the recording when it is available. Playback requires authorized access; the authenticated recording route requires **Voice settings** read access.

Do not use recording availability as the sole test that a call happened. Failed dialing attempts and calls with recording disabled can have a call record without playable audio.

## Use summaries in automations

**Call Finished** can execute before the final AI summary is saved. Its **Summary** field may be empty. For a CRM note, log the outcome first and have a separate follow-up retrieve the completed session before adding summary text. See [Call outcomes](/phone/call-outcomes) and [HubSpot phone automation](/integrations/hubspot/channels/phone#callback-tasks-and-call-notes).

## When something is missing

Check the agent's recording setting, the team's live-transcript setting, your access, and whether the call had connected audio. Reopen the session after processing. If the result is still missing, share the session link, call time with timezone, direction, and affected attempt with support. See [Phone troubleshooting](/phone/troubleshooting).


# SIP Integration
Source: https://docs.open.cx/phone/sip-integration

Bring your own carrier to OpenCX — configure inbound and outbound SIP trunks, route calls to agents, and set up SIP-based call transfers.

<Tooltip>
  SIP
</Tooltip>

trunking lets you route calls through your **own telephony provider**. Configure
trunks from **[Settings → SIP](https://platform.open.cx/settings/sip)**.

<Tip>
  Not using your own carrier? Skip this page — hosted numbers work without SIP.
  See [Create Phone Agent](/phone/create-agent) to get started.
</Tip>

## Provider Compatibility

Before you configure anything in OpenCX, ask your carrier or PBX team for these exact details:

* Confirm they can provide a standard <Tooltip href="/phone/sip-integration">**SIP trunk**</Tooltip> for the call flow you want to support.
* Confirm whether [**inbound**](#inbound-sip-trunks) and [**outbound**](#outbound-sip-trunks) calling are provisioned separately on their side. Many carriers require separate setup for each direction.
* Ask for the <Tooltip>**signaling host**</Tooltip>, <Tooltip>**port**</Tooltip>, and <Tooltip>**transport**</Tooltip> they expect you to use for each direction.
* For inbound calls to OpenCX, confirm your carrier can send digest credentials. Self-serve OpenCX inbound trunks issue a generated username and password.
* For outbound calls from OpenCX, ask whether your carrier authenticates by <Tooltip>**digest credentials**</Tooltip> (username/password) or by <Tooltip>**source IP allowlisting**</Tooltip>.
* If your carrier cannot match calls by credentials or by an IP range, ask whether it can identify them by a <Tooltip>**custom SIP header**</Tooltip>. See [Custom SIP headers](#custom-sip-headers).
* Confirm which <Tooltip>**caller ID numbers**</Tooltip> you are allowed to present on outbound calls.
* If they require <Tooltip>**IP allowlisting**</Tooltip>, allowlist the OpenCX SIP IP ranges below.
* Confirm the carrier supports at least one of the transports and codecs listed below.

<Note>
  If your inbound carrier only supports source IP allowlisting and cannot send
  SIP digest credentials, contact OpenCX before rollout. That setup is not
  self-serve from the dashboard today.
</Note>

### OpenCX SIP IP Ranges

Find the current static SIP IP ranges in **[Settings → SIP](https://platform.open.cx/settings/sip)**. Add all listed ranges to your carrier allowlist when the carrier authenticates outbound calls from OpenCX by source IP.

### Supported Transports And Codecs

For carrier setup, use:

* **Transports:** UDP, TCP, or TLS.
* **Codecs:** G.711 μ-law (PCMU), G.711 A-law (PCMA), or G.722.

OpenCX handles SIP codec negotiation automatically.

### Provider Guides

Some provider-owned guides that are useful when configuring a provider to route calls to an external SIP endpoint:

* [Twilio Elastic SIP Trunking origination settings](https://www.twilio.com/docs/sip-trunking#origination)
* [Telnyx SIP URI Calling](https://developers.telnyx.com/docs/voice/sip-trunking/features/sip-uri-calling)
* [Plivo SIP Trunking with Vapi](https://docs.plivo.com/docs/voice/ai-voice-agents/how-to-integrate-plivo-with-vapi)
* [Sinch Elastic SIP Trunking SIP endpoints](https://developers.sinch.com/docs/est/api-reference/est/sip-endpoints)
* [Wavix SIP Trunking setup guides](https://docs.wavix.com/sip-trunking/guides/setup-guides)

## Inbound SIP Trunks

Route calls from your carrier to OpenCX agents. Inbound trunks are configured entirely on our side from **[Settings → SIP](https://platform.open.cx/settings/sip)**.

What OpenCX provides:

* A SIP endpoint in the region you choose: **Global (auto-route)**, **US**, **EU**, **United Kingdom**, **India**, **Japan**, **Australia**, or **Saudi Arabia**.
* Generated digest credentials (username and password) for your carrier or <Tooltip>PBX</Tooltip> to send calls to OpenCX.
* Routing by the **dialed number** or by the <Tooltip>X-OPENCX-AGENT-ID</Tooltip> header.

What we need from your carrier:

* One or more **verified [BYOC phone numbers](https://platform.open.cx/settings/phone-numbers)** that match the DIDs your carrier sends in the <Tooltip>SIP INVITE</Tooltip>. You can also [contact us](mailto:support@open.cx) to manually add verified numbers.
* A trunk on the carrier or PBX side that points to the OpenCX SIP endpoint using the generated credentials.

## Outbound SIP Trunks

Make outbound calls from OpenCX through your carrier. Outbound trunks are configured on our side from **[Settings → SIP](https://platform.open.cx/settings/sip)**.

What OpenCX supports:

* <Tooltip>
    **Transports**
  </Tooltip>
  : **UDP** (default), **TCP**, or **TLS**.
* Authentication by <Tooltip>**digest credentials**</Tooltip> (username/password) or by <Tooltip>**source IP allowlisting**</Tooltip>.
* [**Custom SIP headers**](#custom-sip-headers) sent with every call placed through the trunk.
* A **number format** per trunk, so the dialed number and caller ID are written the way your carrier routes them.

What we need from your carrier:

* The outbound **SIP host** and **port**.
* The **caller ID number** approved for outbound presentation.
* The outbound authentication method: digest username/password, or source IP allowlisting. For IP allowlisting, add the OpenCX SIP IP ranges (found in **[Settings → SIP](https://platform.open.cx/settings/sip)**) to the carrier-side rule.
* Any header name and value the carrier expects on each call, if it identifies your traffic that way.
* The number format the carrier expects, for example with or without a leading `+`.

### Number format

Carriers differ on how they expect phone numbers to be written, and usually reject a call in another format as not found. Set **Number format** on the outbound trunk to match your carrier:

| Option | Example |
| - | - |
| Unchanged | The number exactly as saved on the contact |
| International with + | `+966512345678` |
| International, digits only | `966512345678` |
| International with 00 | `00966512345678` |

The format applies to the dialed number and the caller ID on every call through the trunk, including calls placed by teammates, and to **Test connection**. Sessions, contacts, and webhooks keep the number as it was entered.

Only numbers saved with a leading `+` or `00` are rewritten. Anything else, such as bare digits, local numbers, or short extensions, is sent unchanged, so save contact numbers in international form with a `+` for the format to apply.

## SIP Transfer Destinations

Route call transfers through SIP instead of the public phone network.

Transfer destinations are managed at the organization level and then assigned to agents.

* **Phone** destinations transfer to an E.164 phone number.
* **SIP** destinations transfer to a SIP URI such as `sip:support@pbx.example.com`. Optional <Tooltip>digest authentication</Tooltip> (username/password) is supported for SIP endpoints.
* **Custom** destinations end the call and are useful when workflows handle pre-transfer or post-transfer behavior.

SIP destinations can also send [custom SIP headers](#custom-sip-headers) with every transferred call. A Classical IVR can connect a caller to a SIP destination and take them back afterwards; see [Transfers to a SIP destination](/phone/call-flows#transfers-to-a-sip-destination).

### Caller ID, encryption and allowed headers

Edit the destination in **[Settings → SIP](https://platform.open.cx/settings/sip)** to match what the endpoint requires:

* **Always send the caller's number**: the endpoint receives the caller's own number as `From` on every transfer, and callers who hide their number are sent as `anonymous`. OpenCX never falls back to your organization's number, even if the endpoint rejects the caller's. It cannot be combined with a fixed **Caller ID**.
* **Transport**: the protocol used for the endpoint's signalling. Choose **TLS** for endpoints that require encrypted signalling, usually on port `5061`.
* **Encrypt call audio (SRTP)**: **When the endpoint supports it** encrypts audio whenever the endpoint offers it; **Always** fails the transfer when the endpoint cannot encrypt. Pair it with TLS.
* **Send only allowed headers**: the endpoint receives only the header names you list, matched without regard to letter case. The list covers the destination's custom headers, the headers IVR transfer steps set, and the identifiers OpenCX adds to transfers. Add `X-OPENCX-SESSION-ID` when the endpoint hands calls back. An empty list sends no custom headers. Custom headers missing from the list are flagged in the form and are not sent.

**Test connection** uses the transport, encryption and allowed headers currently in the form. Saving a change to any of them, or to the destination's address, credentials or custom headers, rebuilds the destination's connection with all of its current settings; the next transfer uses them. Transfers never change the connection themselves: a destination saved before **Transport** applied to transfers keeps its existing connection until you save one of these settings.

## Custom SIP headers

Add custom SIP headers to an outbound trunk or a SIP transfer destination when the other side needs more than credentials or an IP allowlist to recognize your calls. A common case is a carrier that matches calls to your account by a shared key in a header, because it cannot match on a range of source IPs.

To add one, open **[Settings → SIP](https://platform.open.cx/settings/sip)**, create or edit the outbound trunk or SIP transfer destination, and use **Custom SIP headers → Add header**. You need permission to edit voice channel settings.

* Headers set on an **outbound trunk** are sent on every call placed through that trunk.
* Headers set on a **SIP transfer destination** are sent on every call transferred to that destination.
* **Test connection** sends the headers currently in the form, so you can confirm the carrier accepts them before saving.

Rules for headers:

* The name must start with `X-` and use only letters, digits, `.`, `_`, or `-`, for example `X-Customer-Key`.
* Names starting with `X-OPENCX-` are reserved for the headers OpenCX adds to each call.
* The value can be up to 255 printable ASCII characters.
* You can add up to 20 headers per trunk or destination.

<Note>
  Header values are stored encrypted and hidden after you save. When you edit a trunk or destination, leave a value blank to keep it, type a new value to replace it, or remove the header to stop sending it. Treat a shared key like a password and send it to your carrier over a secure channel.
</Note>

Saved values are only reused for the host they were saved with. If you change the **SIP host**, enter each header value again before you save or run **Test connection**. Changing only the port, transport, or extension keeps them.

If two people edit the same trunk or destination at once, the second save is rejected so it cannot undo the first. Reload the page and apply the change again.

On a transferred call, a header set on the destination always takes precedence over a header with the same name that arrived on the original call.

If calls are rejected after you add a header, confirm the exact header name and value with your carrier, including letter case, and check that the carrier reads it from the initial call request (the SIP INVITE).

## Advanced: Dynamic Agent Routing

For advanced setups, use the <Tooltip>X-OPENCX-AGENT-ID</Tooltip> SIP header to route inbound calls to a specific agent dynamically. Include the agent's ID (shown on the agent settings page) in the header when sending calls to the OpenCX SIP endpoint.

This is useful when:

* Multiple agents share the same trunk
* Your <Tooltip>PBX</Tooltip> or carrier decides which agent should answer based on <Tooltip>IVR</Tooltip> logic or caller data

### Supported SIP Headers

OpenCX forwards SIP `X-*` headers from inbound calls. These headers have first-class behavior:

* `X-OPENCX-AGENT-ID`: route the call to a specific phone agent.
* `X-OPENCX-CONTACT-ID`: attach the call to an existing OpenCX contact in the same organization. If the contact is missing or belongs to another organization, OpenCX falls back to phone-number matching.
* `X-OPENCX-CONTACT-CUSTOM-DATA`: JSON object merged into the contact. Values must be strings, numbers, or booleans.
* `X-OPENCX-SESSION-CUSTOM-DATA`: JSON object merged into the call session. Values must be strings, numbers, or booleans.
* `X-OPENCX-AGENT-LANGUAGE`: override the agent language for this call. Use one ISO code or a comma-separated list supported by the phone agent language settings.
* `X-OPENCX-INCLUDE-INSTRUCTION-IDS`: comma-separated instruction IDs to include for this call.

Other `X-*` SIP headers are stored on the session with the leading `X-` prefix removed.

## Related Documentation

<CardGroup>
  <Card title="Create Phone Agent" icon="plus" href="/phone/create-agent">
    Set up an agent to receive SIP-routed calls.
  </Card>

  <Card title="Agent Configuration" icon="sliders" href="/phone/agent-config">
    Assign trunks and numbers under Telephony & Routing.
  </Card>

  <Card title="Outbound Calls" icon="phone-arrow-up-right" href="/phone/outbound-calls">
    Launch calls from the dashboard, API, or workflows.
  </Card>
</CardGroup>

## Validate the complete route

Test inbound calling, outbound calling, and transfers separately. A successful inbound call does not validate outbound credentials or caller identity. Confirm the dialed number is assigned to the intended agent, or send an explicit `X-OPENCX-AGENT-ID` header. See [Numbers and routing](/phone/numbers-and-routing) for routing precedence and human-answering behavior.

For no-ring, rejected-call, or audio failures, use [Phone troubleshooting](/phone/troubleshooting). Keep the exact call time and timezone, caller and destination numbers, session link if created, and your carrier's result for the same attempt.


# Phone calling troubleshooting
Source: https://docs.open.cx/phone/troubleshooting

Diagnose calls that do not ring, wrong routing, busy or rejected results, audio problems, failed transfers, and missing recordings or follow-ups.

Start with one reproducible call to a phone you control. Record the exact time and timezone, direction, caller number, destination, and OpenCX session link. Use the call ID when available to distinguish repeat attempts.

## Browser test works, real phone call does not

A browser **Test Call** checks the agent without validating the carrier route. Test a real inbound and outbound call separately. Check the number's verification and assignment in **[Settings → Phone Numbers](https://platform.open.cx/settings/phone-numbers)** and the relevant trunk in **[Settings → SIP](https://platform.open.cx/settings/sip)**.

## Incoming call does not ring or reaches the wrong person

* Confirm the number is routed to OpenCX at your carrier and is in the expected workspace.
* Check **Inbound Agent**. An unassigned number can ring teammates instead of AI.
* For SIP, check the dialed number and any `X-OPENCX-AGENT-ID` override. An agent header can take precedence over number assignment.
* For team calls, keep the dashboard open, enable availability and **Available for calls**, and check that the intended teammates are not already on a call or wrapping up.
* For a team destination, remember that an empty eligible team pool can fall back to available teammates across the workspace.

If no session is created, collect the carrier's result for the same call time. Absence of an OpenCX session alone does not identify where the call failed.

## Outbound call fails or shows the wrong caller ID

Check the destination's international format, the selected agent's outbound caller/trunk configuration, and the chosen number's verification. For a human call, check the caller number selected in the dialer. Your carrier must allow the destination and caller identity on that route.

An inbound trunk working does not prove outbound calling is configured. Likewise, successful human dialing does not prove the AI agent uses the same route. Compare the AI agent's outbound settings and the selected human caller number before retrying.

## Busy, declined, voicemail, or unknown

Use [Disposition](/phone/call-outcomes), not just **Outcome = Unanswered**. Busy requires an explicit busy result. A declined call can reflect rejection along the route rather than a person pressing Decline. `unknown` is an inconclusive result, not proof of a human answer.

Test voicemail with a number you control. Detected outbound voicemail ends the AI call without leaving a message. If detection is inconsistent, include the language and call examples in your support request.

## Connected, but audio is missing

For dashboard calls, check browser microphone permission, the selected microphone and speaker, mute, and hold. Confirm whether the customer hears you, you hear them, or neither side hears audio. Test a second device or network to narrow the problem.

For SIP calls, compare your carrier's codec and transport configuration with [SIP setup](/phone/sip-integration). Give support the exact call time and which audio direction failed; a connected status alone does not confirm usable two-way audio.

## Transfer fails

Confirm the destination is assigned to the AI agent and that its phone number or SIP address is correct. A **Custom** destination ends the call; it is not a dialable transfer target. A **Team** destination requires eligible teammates.

Test the destination directly, then test the actual transfer path. For a dashboard consultation transfer, cancel an unanswered destination and resume the customer call. Verify [team availability and transfer behavior](/phone/human-calling) rather than assuming every failed transfer has the same fallback.

## Recording, transcript, or summary is missing

Check [recording and transcript settings](/phone/recordings-and-transcripts). Audio recording can be off while transcript messages still exist. A human call's post-call summary needs usable text or audio. Recording and summary processing may finish after hang-up.

For CRM automation, **Call Finished** does not guarantee the final summary is ready. Log the outcome separately and enrich the note once text is available.

## Follow-up did not happen

1. Confirm the intended workflow version is active.
2. Inspect its run and actual trigger fields: direction, disposition, contact, and call ID.
3. Check that the event applies to that calling path. An AI outbound trigger recipe should not be assumed to cover all human calls.
4. For WhatsApp, inspect **Sent** and **Error**; a completed workflow can still contain an unsuccessful send.
5. For **Send Webhook**, inspect **Is Success**, **Status Code**, and the receiver's result.
6. For callbacks, confirm the timezone, next scheduled occurrence, **Run Limit**, and whether the one-shot schedule already fired.

See [Follow-up workflows](/phone/follow-up-workflows) for complete recipes.

## What to send support

Send the workspace, session link, call ID if present, exact timestamp and timezone, direction, caller and destination numbers, agent name, and expected versus actual behavior. Include the workflow run link for automation failures and the carrier's call result for routing failures. Never include passwords or API keys.

## Call shows Reconnecting

Keep the call card open while **Reconnecting…** is displayed. The dashboard attempts to restore your microphone and incoming audio automatically. **Linking…** means it is still waiting for incoming audio; a restored connection alone does not confirm that you can hear the caller. You can still choose **End call** to hang up.

If the card shows **Failed**, check your microphone permission and network connection. Send support the session link and the time of the interruption if the problem repeats.

## Call interrupted after refreshing

Return to the same dashboard tab and organization promptly. Customer calls allow a 30-second reconnection window after the browser disconnects. Check microphone permission if the call card returns without audio. A call that already ended cannot be recovered by refreshing again.

If an incoming call does not appear, verify that a dashboard tab is open to the organization receiving it. Being signed in to a different organization does not make that tab available for its calls.


# Voice SDK integration
Source: https://docs.open.cx/phone/voice-sdk

Add voice support to your web, iOS, or Android app. Authenticate customers, connect AI or human teams, and manage call controls and session status.

<Warning>
  The Voice SDK is an opt-in preview. Enable app calling in your organization’s Voice & Telephony settings before integrating. Obtain the preview packages from your OpenCX contact; public package registry availability is not implied by this guide.
</Warning>

Add a **Call support** button to your app. Customers can speak with an AI phone agent, wait for a human team, or remain on the same call while the AI hands off to a human. Your app controls the interface; the SDK handles audio and call controls.

The SDK supports customer-initiated calls while your support screen is active. Incoming-call push notifications, system call-screen integration, and automatic background-call support are not included. Configure and test any app background audio behavior separately.

## Package availability

Use the package version confirmed by your OpenCX contact. Until that version is published, continue using the supplied preview packages described below.

After public release, the installation locations are:

| Platform | Package location |
| - | - |
| Web | `npm install @opencx/voice@0.1.0` |
| iOS | Add `https://github.com/opencx-labs/voice-ios` in Xcode and select version `0.1.0`. |
| Android | Add `implementation("cx.open:voice-android:0.1.0")` from Maven Central. |

For Android, include `google()`, `mavenCentral()`, and `maven("https://jitpack.io")` in your dependency repositories so the complete dependency graph can resolve. All three SDKs use the MIT license.

Installing a package does not enable calling for your organization. The organization’s app calling setting and your authenticated server integration are still required.

## Enable app calling

1. Open **Settings → Voice & Telephony** in the organization your app will use.
2. Under **App calling**, turn on **Allow calls from apps**. You need permission to edit Voice & Telephony settings (`settings-channels-voice:write`).
3. Configure your server with an API key that has `phone:write`, then follow the authentication steps below.

New organizations have app calling turned off. Changes take effect for new calls without a deployment and are recorded in the organization’s audit log. This setting is independent of telephone-number calling.

Turning it off blocks new call creation and prevents previously issued credentials from starting a call. Active calls can finish, reconnect, and hang up within their existing duration limit. Turning it back on allows new calls; create fresh credentials for attempts that already ended.

The toggle does not replace API-key scopes, customer authentication, contact blocking, or destination checks.

## Authenticate on your server

Your server must authenticate the customer and resolve their OpenCX contact. It then chooses an authorized phone agent or support team and calls [Create an app voice call](/api-reference/phone/create_web_call) with an API key holding `phone:write`.

Never put a permanent API key in a website or mobile app. Do not accept an arbitrary contact ID or privileged routing destination from the client. Membership in your app must be checked before returning call credentials.

```typescript theme={"dark"}
// Inside your authenticated server route:
// contactId is resolved from the signed-in customer, not the request body.
const response = await fetch('https://api.open.cx/phone/web-calls', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OPENCX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    requestId, // UUID; keep the same value when retrying this request
    contactId,
    destination: { type: 'agent', id: phoneAgentId },
    maxDurationSeconds: 1800,
  }),
});
if (!response.ok) {
  // Return an appropriate error to your app; never log returned credentials.
  throw new Error(`Call creation failed (${response.status})`);
}
const credentials = await response.json();
// Respond only to the authenticated customer, with Cache-Control: no-store.
```

Use `{ type: 'team', id: teamId }` to start with a human team. The team must belong to your organization and have support enabled. App calls use that team's routing and queue settings. Direct team calls and AI transfers to a specific team do not spill into unrelated teams when nobody is available. Team eligibility is checked again when a human accepts, so a ringing notification does not preserve access after they leave the team.

For AI calls, configure the agent's languages and permitted human-team transfer destinations in the dashboard. An AI team-transfer destination with no selected team rings eligible, available agents across your organization. App-call agents support team and end-call destinations. Agents with telephone-number or external telephony transfer destinations are rejected; use a dedicated app-support agent if your phone agent needs those destinations. No dialed phone number is available to select a country flow: choose the appropriate destination on your server.

Call creation returns `callId`, `sessionId`, `controlToken`, and `expiresAt`. Pass this OpenCX credentials object to the SDK unchanged. Treat `controlToken` as a secret; do not log it, place it in page URLs, or store it persistently. It authorizes only this call. The SDK establishes the audio connection and activates the call automatically. An abandoned connection attempt expires automatically, and active calls have a server-enforced duration limit.

Your app uses only the OpenCX SDK's call methods, states, and errors. No separate audio-service account, credentials, client initialization, or event handling is required. Audio connection details are managed internally by the SDK and are not part of the supported integration contract.

<Note>
  Update preview SDK packages and the matching backend together. Earlier preview responses included `serverUrl` and `participantToken`; these fields are no longer returned by call creation. Remove app code that reads those fields or creates its own audio connection, and pass the OpenCX credentials directly to the updated SDK. Start a new call after updating.
</Note>

Reuse `requestId` only for retries of the same creation attempt. Different settings with the same ID fail. After a call starts or ends, use a new request ID for another call. One customer can have one active app call at a time.

## Web

Choose an npm integration or a script tag for a plain HTML or server-rendered app. Both provide the same calling methods and events; your app supplies the buttons and interface.

### npm integration

Use Node.js 22.22 or later for the npm tooling. Install the preview package supplied by OpenCX:

```bash theme={"dark"}
npm install ./opencx-voice-0.1.0.tgz
```

```typescript theme={"dark"}
import { OpenCXVoice } from '@opencx/voice';

const voice = new OpenCXVoice({
  getToken: async ({ requestId, signal }) => {
    const response = await fetch('/api/support/voice-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ requestId }),
      signal,
    });
    if (!response.ok) throw new Error('Unable to start support call');
    return response.json();
  },
});

voice.on('stateChanged', state => updateCallStatus(state));
voice.on('error', error => showCallError(error.message));

// Run from the customer's button click.
await voice.start();
await voice.setMuted(true);
voice.setSpeakerEnabled(false);
await voice.end();
// On permanent component removal:
await voice.dispose();
```

`setMicrophone(deviceId)` and `setAudioOutput(deviceId)` select audio devices where the browser supports them. Choose the microphone before calling `start()`, or wait for `start()` to finish before changing it. If audio playback is blocked, show a button that calls `resumeAudio()`. Microphone access requires HTTPS (localhost is allowed for development). Embedded frames require microphone permission from the host page. Customers can refuse or revoke microphone access; display the SDK error and offer another support channel.

`setMuted()` requires an active call on web, iOS, and Android. Disable mute controls before a call starts and after it ends, and handle failures instead of updating the UI as though mute succeeded.

SDK errors use OpenCX types: `VoiceError` on web and iOS, and `VoiceException` on Android. Handle these alongside call states; do not depend on internal audio error messages or types. On web, `call_failed` reports an operation that could not complete without exposing transport-specific error details.

Subscribe before calling `start()`. The states are `idle`, `connecting`, `waiting`, `queued`, `connected`, `reconnecting`, and `ended`. A queue notification or ringing agent is not proof a human answered. `connected` reflects an observed ready support participant. An `ended` state means the local microphone is stopped; if server hangup fails, an error is also emitted and server cleanup remains responsible for the room.

### Script tag: no npm or build step

<Note>
  The standalone browser bundle starts with web SDK version `0.2.0`. Confirm this version is available before using its download URL; version `0.1.0` does not contain the bundle. Native SDK versions do not need to change for this integration.
</Note>

Download `dist/opencx-voice.min.js` and `dist/opencx-voice.min.js.LEGAL.txt` from the confirmed release of `@opencx/voice`. Copy both files to your website's `/scripts/` directory. No Node.js runtime, npm installation, or JavaScript build step is required in your application. Your existing server can use any language.

Add these tags and controls to your HTML template. The SDK must load before your own script:

```html theme={"dark"}
<script defer src="/scripts/opencx-voice.min.js"></script>
<script defer src="/scripts/support-calling.js"></script>

<button id="call-support" type="button">Call support</button>
<button id="end-call" type="button" disabled>End call</button>
<button id="resume-audio" type="button">Resume audio</button>
<p id="call-status" role="status">idle</p>
<p id="call-error" role="alert"></p>
```

Create `/scripts/support-calling.js`:

```javascript theme={"dark"}
const status = document.getElementById('call-status');
const errorMessage = document.getElementById('call-error');
const callButton = document.getElementById('call-support');
const endButton = document.getElementById('end-call');
const voice = new OpenCXVoice.OpenCXVoice({
  getToken: async ({ requestId, signal }) => {
    const response = await fetch('/api/support/voice-token', {
      method: 'POST',
      credentials: 'same-origin',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ requestId }),
      cache: 'no-store',
      signal,
    });
    if (!response.ok) throw new Error('Unable to start a support call');
    return response.json();
  },
});
voice.on('stateChanged', (state) => {
  status.textContent = state;
  const idle = state === 'idle' || state === 'ended';
  callButton.disabled = !idle;
  endButton.disabled = idle;
});
voice.on('error', (error) => { errorMessage.textContent = error.message; });
async function perform(action) {
  errorMessage.textContent = '';
  try {
    await action();
  } catch (error) {
    errorMessage.textContent = error instanceof Error ? error.message : 'Call action failed';
  }
}
callButton.onclick = () => perform(() => voice.start());
endButton.onclick = () => perform(() => voice.end());
document.getElementById('resume-audio').onclick = () => perform(() => voice.resumeAudio());
```

Implement `/api/support/voice-token` on **your server**, following [Authenticate on your server](#authenticate-on-your-server). Require a signed-in customer, apply your application's CSRF protection, and resolve the contact and permitted destination there. Forward `requestId` to call creation and return the credentials only to that customer with `Cache-Control: no-store`. The permanent OpenCX API key must never appear in the template or browser script.

The script exposes `OpenCXVoice.OpenCXVoice` and `OpenCXVoice.VoiceError`. The same `setMuted`, `setSpeakerEnabled`, device-selection, and cleanup methods shown above apply. When your app removes the calling screen, await `voice.dispose()` to release the microphone and end the call.

After version `0.2.0` is published, an alternative to self-hosting is the exact URL `https://cdn.jsdelivr.net/npm/@opencx/voice@0.2.0/dist/opencx-voice.min.js`. Keep the version pinned. Copy `integrity` from that release's `dist/browser-integrity.json` into the script tag's `integrity` attribute and set `crossorigin="anonymous"`. Do not reuse a hash from a different version or modified file. Keep the legal notices with any redistributed copy.

Use HTTPS and a modern browser with microphone and real-time audio support; localhost is supported for development. This installation method does not add support for obsolete browsers. Start calls from a user action, and offer Resume audio if playback is blocked. Embedded frames need microphone permission from the parent page.

If your app sets a Content Security Policy, permit the chosen script source, your credential route, the OpenCX API, and the audio connection endpoints supplied for your integration. The bundle does not require `unsafe-eval` or inline scripts. Keep the rest of your policy restricted.

## iOS

Add the supplied `OpenCXVoice` Swift package to your app. Include `NSMicrophoneUsageDescription` in your app's privacy settings. The SDK requests audio permission before creating a call.

```swift theme={"dark"}
import OpenCXVoice

let voice = try OpenCXVoice { requestId in
    // Authenticate with your backend and decode its response:
    try await supportAPI.voiceCredentials(requestId: requestId.uuidString)
}
voice.onStateChanged = { state in updateCallStatus(state.rawValue) }
voice.onError = { error in showCallError(error.localizedDescription) }
try await voice.start()
try await voice.setMuted(true)
try await voice.setSpeakerEnabled(true)
try await voice.end()
```

Keep the instance alive until the call ends. UI callbacks run on the main actor. End the call before discarding its owner. The speaker setting selects speakerphone or the system audio route. Test interruptions, Bluetooth, route changes, and app backgrounding on physical devices before rollout.

## Android

Add the supplied `cx.open:voice-android:0.1.0` package from your configured preview repository. Request `RECORD_AUDIO` permission before starting a call. Use the SDK from the main thread and collect `state` in your app's lifecycle.

```kotlin theme={"dark"}
import cx.open.voice.OpenCXVoice

val voice = OpenCXVoice(context, getToken = { requestId ->
    // Authenticate with your backend and decode with VoiceCredentials.fromJson.
    supportApi.voiceCredentials(requestId)
})
voice.onError = { error -> showCallError(error.message) }
voice.start()
voice.setMuted(true)
voice.end()
// When the owning support screen is permanently removed:
voice.dispose()
```

Do not cancel the only call owner without ending the call. Audio routing follows the system route. Background calling and incoming call alerts require additional app integration and are outside this preview.

## Session history and recording

`sessionId` identifies the OpenCX support session. App calls use the existing voice session history and configured recording behavior. Choosing app calling does not grant permission to read other sessions. Make your recording notice and retention policy available before the customer starts speaking.

## Troubleshooting

| Symptom | Check |
| - | - |
| Creation returns 403 | **Allow calls from apps** in Settings → Voice & Telephony, API key scope, and contact blocking. |
| Creation returns 404 | Contact and destination belong to the same organization; the team has support enabled. |
| Creation returns 409 | An existing active call or reuse of a request ID with different settings. |
| Call stays waiting | Network access, destination readiness, or unavailable support agents. The SDK ends a continuous wait of more than 60 seconds; time already connected or queued does not count toward that wait. |
| Microphone denied | Device/browser permission and the host page's frame permissions. |
| Connected but silent | Device route, muted speaker, or browser playback permission; offer `resumeAudio()` on web. |
| Call ends during a network change | A brief reconnect is supported, but a prolonged disconnect ends the call. Offer a fresh call attempt. |

Test your supported browser and device versions, human acceptance, unavailable teams, queues, hangup during connection, and Wi-Fi/cellular changes before enabling this for customers.

## Testing your integration

Request the SDK source examples from your OpenCX contact before following these checks. The installed packages do not include the test apps or broker. The source examples include setup instructions in `sdks/voice-web/examples/README.md`, `sdks/voice-android/example/README.md`, and `sdks/voice-ios/example/README.md`.

Use a dedicated test contact and support destination. The supplied web and native examples call an authenticated local test broker; the permanent organization API key remains on that server. A random test session token is required to use the broker. This fixed-contact broker is for local testing: your deployed app must authenticate each customer and authorize their contact and destination on your own backend.

For local development, the SDKs accept an HTTP API URL only on `localhost` or `127.0.0.1`. Use HTTPS for other hosts. The iOS sample uses local-network transport settings, and the Android sample allows local test traffic. Keep these development settings out of your production app.

Run the Android example on an emulator and the iOS example on a simulator to check permission handling, call states, mute/unmute, hangup, cancellation, and repeated starts. The supplied native UI checks require a running test broker and an available support destination; compiling an app alone does not verify a call.

Before rollout, also verify two-way speech and human acceptance, unavailable teams, interrupted networks, and server-enforced expiry. Match each result to its OpenCX `sessionId`. Simulators do not establish Bluetooth quality, cellular switching, locked-screen behavior, or performance on physical devices. Complete those checks on the devices your customers use.


# Plan your rollout
Source: https://docs.open.cx/plan-your-rollout

Pick the goal, the channels, and the order to roll out OpenCX — by the outcome you care about and the role you play on the team.

Quickstart got one agent live. This page helps you decide what to do next — based on the outcome you want and the role you play on the team. If you're rolling out across more than one channel, work through the goals first, then the role-specific reading list.

## Pick a goal

<CardGroup>
  <Card title="Reduce ticket volume in your existing helpdesk" icon="chart-line-down" href="/dashboard/introduction">
    Connect Zendesk, Front, Intercom, or HubSpot. The AI handles routine tickets; your team gets the rest with full context.
  </Card>

  <Card title="Answer 24/7 across messaging channels" icon="comments" href="/build-agents/get-started">
    Chat widget, WhatsApp, and SMS — same AI, every channel.
  </Card>

  <Card title="Stand up a voice agent for inbound calls" icon="phone" href="/phone/introduction">
    An AI phone agent that answers, looks things up, and transfers to a person when needed.
  </Card>

  <Card title="Automate API work the team handles by hand today" icon="bolt" href="/actions/introduction">
    Teach the AI to look up orders, update fields, and call your APIs — so customers stop waiting on a human.
  </Card>
</CardGroup>

## Pick the order

<Steps>
  <Step title="Train the AI on what it should know">
    Upload your help center, sync from Zendesk, Notion, or Confluence, or crawl your site. The AI's answers are only as good as the content it reads from. See [Agent Training](/knowledge/introduction).
  </Step>

  <Step title="Pilot one channel end-to-end">
    Pick the channel with the most predictable questions — often the chat widget or email. Get [Autopilot](https://platform.open.cx/settings/autopilot) answering, prove the resolve rate, then expand. See [Build Agents](/build-agents/get-started).
  </Step>

  <Step title="Wire up handoff to your helpdesk">
    Tickets the AI can't handle should land where your team already works. See [Integrations](/dashboard/introduction).
  </Step>

  <Step title="Add Actions for the API work">
    Order lookups, refunds, address updates — replace the boring back-and-forth. See [AI Actions](/actions/introduction).
  </Step>
</Steps>

## Pick by role

<CardGroup>
  <Card title="CX operations admin" icon="headset" href="/how-opencx-works">
    Read 'How OpenCX Works' and 'Architecture overview', then pilot one channel.
  </Card>

  <Card title="Evaluator or decision maker" icon="magnifying-glass" href="/architecture-overview">
    Start with 'Architecture overview' for the data-flow and control story. Bookmark 'Core concepts' for shared vocabulary.
  </Card>

  <Card title="Developer" icon="code" href="/api-reference/authentication">
    Skip to API authentication, then MCP and Actions. The dashboard isn't required for backend automation.
  </Card>
</CardGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    If you skipped this, do it first.
  </Card>

  <Card title="How OpenCX Works" icon="diagram-project" href="/how-opencx-works">
    The five pieces every agent shares.
  </Card>

  <Card title="Architecture overview" icon="sitemap" href="/architecture-overview">
    Where data lives and what your team controls.
  </Card>

  <Card title="Core concepts" icon="book" href="/core-concepts">
    Vocabulary in one place.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.open.cx/quickstart

Get a live OpenCX AI agent on your site in under 10 minutes — join an organization, train it on a knowledge source, embed the chat widget, and watch Autopilot answer.

This is the fastest path from zero to a live AI agent on your site. Pick the channel you want first — the chat widget takes the least setup, so we start there.

<Steps>
  <Step title="Join your organization">
    Sign in at [platform.open.cx](https://platform.open.cx) and select your organization. If you have no organizations, ask your organization admin to invite you.

    Organization admins can create an additional organization from the organization switcher. See [Organization creation and environments](/organizations).
  </Step>

  <Step title="Train the AI with your content">
    From **Settings → Knowledge**, connect one source:

    <Tabs>
      <Tab title="Website">
        Paste your help site URL. The crawler fetches every linked page and indexes it automatically. See [Train via integrations](/knowledge/sources/overview).
      </Tab>

      <Tab title="Help Center">
        Create a help center and write a few articles. See [Help Center overview](/help-center/overview).
      </Tab>

      <Tab title="Training scenario">
        Type a common question and the answer you want the AI to give. See [Training scenarios](/ai-instructions/training-scenarios).
      </Tab>
    </Tabs>
  </Step>

  <Step title="Enable Autopilot">
    From [Settings → Autopilot](https://platform.open.cx/settings/autopilot), turn on the **Web** channel. The AI will now reply to chat messages from visitors.
  </Step>

  <Step title="Embed the widget">
    Copy the snippet from [Channels → AI Chat Widget](https://platform.open.cx/channels/configure/widget) and paste it before `</body>` in your site. See the full [widget guide](/widget/install-widget) for framework-specific installs (Next.js, React, Vue, plain HTML).
  </Step>

  <Step title="Test it">
    Open your site. Click the widget. Ask a question the AI should know from the content you connected. The reply should land within a second, and the session appears live in your [inbox](https://platform.open.cx/inbox).

    If the AI does not know the answer, it will escalate to your team instead of guessing — see [Handoff](/handoff/introduction).
  </Step>
</Steps>

<Tip>Chat widget not the right first channel? Try [Email](/email/forwarding), [SMS](/sms/connect-sms), [WhatsApp](/whatsapp/connect-whatsapp), or [Phone](/phone/create-agent) instead — the pattern is the same.</Tip>

## What to do next

<CardGroup>
  <Card title="How OpenCX Works" icon="diagram-project" href="/how-opencx-works">
    The mental model — channels, knowledge, autopilot, actions, handoff.
  </Card>

  <Card title="Core Concepts" icon="book" href="/core-concepts">
    The terms that show up everywhere: sessions, autopilot, handoff.
  </Card>

  <Card title="Build Agents" icon="robot" href="/build-agents/get-started">
    Stand up an agent on every channel your customers use.
  </Card>

  <Card title="AI Actions" icon="bolt" href="/actions/introduction">
    Teach the AI to call your APIs — lookups, updates, real work.
  </Card>
</CardGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Agent Training" icon="book" href="/knowledge/introduction">
    Everything your AI reads from — help center, training scenarios, connected sources.
  </Card>

  <Card title="Integrations" icon="plug" href="/dashboard/introduction">
    Connect your helpdesk, CRM, or e-commerce platform.
  </Card>

  <Card title="AI Safety" icon="shield" href="/safety/introduction">
    Inspect mode, PII redaction, prohibited topics.
  </Card>

  <Card title="MCP Server" icon="network-wired" href="/mcp/introduction">
    Operate OpenCX from Claude Desktop, Cursor, and VS Code.
  </Card>
</CardGroup>


# Collect Customer Satisfaction
Source: https://docs.open.cx/resources/csat

Send a CSAT survey after a conversation resolves, capture the 1–5 rating and comment, and see the trend in your reports.

<Tooltip href="/api-reference/csat">**CSAT**</Tooltip> runs once a conversation resolves, collects a 1–5 rating and an optional comment, and feeds back into your reports and workflows. The survey reaches the customer on the **same channel** the conversation lived on — an email conversation gets an email survey, an SMS conversation gets an SMS.

<CsatFlow />

<Info>
  CSAT is off by default. Enable it per channel from [Settings → CSAT](https://platform.open.cx/settings/csat).
</Info>

## How it works

* After a session is marked resolved, OpenCX waits the delay you chose and sends the survey on the same channel the customer used.
* The customer rates 1–5 (😡 😞 😐 🙂 😍) and can optionally leave a comment.
* The score lands back on the session, in your reports, on the webhook stream, and as a workflow trigger.

## Enable CSAT

<Steps>
  <Step title="Open Settings → CSAT">
    Head to [Settings → CSAT](https://platform.open.cx/settings/csat) in your OpenCX dashboard.
  </Step>

  <Step title="Turn on auto-send">
    Switch on **Auto-send CSAT after session closes** and pick a delay: **Now**, **5m**, **15m**, or **1h**. The survey fires that long after the session is marked resolved.
  </Step>

  <Step title="Pick your channels">
    Under **Channel Configuration**, enable the channels you want surveys to run on — Web Chat, Email, Phone, WhatsApp, SMS, Slack, API, or Web Voice. Each channel toggles independently.
  </Step>

  <Step title="Save">
    Click **Save Changes**. New resolutions from this point forward will trigger a survey on any enabled channel.
  </Step>
</Steps>

<Warning>
  Native CSAT auto-send is only available when your ticketing system is set to **Open**. If a third-party ticketing integration owns resolution in your org, trigger CSAT from a [workflow](#trigger-csat-from-a-workflow) instead.
</Warning>

## The rating scale

| Score | Emoji | Label |
| - | - | - |
| 1 | 😡 | Terrible |
| 2 | 😞 | Poor |
| 3 | 😐 | Okay |
| 4 | 🙂 | Good |
| 5 | 😍 | Excellent |

Low scores (1–2) prompt the customer for a comment before they can skip — the extra context makes bad scores actionable.

## Supported channels

| Channel | Delivery |
| - | - |
| Web Chat | In-widget rating card |
| Email | Branded email with clickable emoji ratings |
| SMS | Short text with a rating link |
| WhatsApp | WhatsApp message with a rating link |
| Phone | SMS follow-up with a rating link |
| Web Voice | Email follow-up with a rating link |
| Slack | Thread reply with a rating link |
| API | Programmatic — trigger via API and collect the submission over webhook |

## Where responses land

* **Inbox.** Open the session in [Inbox](https://platform.open.cx/inbox) — the timeline shows a **CSAT requested** event and, once submitted, a **CSAT submitted** event with the selected emoji and comment.
* **Reports.** Filter and export scored sessions from [Reports → Data Export](https://platform.open.cx/reports/data-export) using the **CSAT Score** and **CSAT Comment** columns.
* **Webhooks.** Subscribe to `csat.requested` and `csat.score_submitted` to pipe scores into your data warehouse or an alerting channel — see the [CSAT API reference](/api-reference/csat).

## Trigger CSAT from a workflow

When auto-send doesn't fit — for example you only want surveys on sessions with positive sentiment, or you want branching logic on low scores — drive CSAT from the [workflow builder](https://platform.open.cx/workflows) instead.

* **Send CSAT Request** action — send the survey on demand for a specific session or conversation.
* **Generate CSAT Link** action — return the rating URL without sending anything, so you can paste it into a custom outbound message.
* **Get CSAT Score** action — branch on a submitted score. *If score \< 3, notify a supervisor and reopen the session.*
* **CSAT Score Submit** trigger — fires every time a customer submits a rating, with the score and comment in the payload.

## Good To Know

<AccordionGroup>
  <Accordion title="One survey per conversation" icon="arrows-rotate">
    OpenCX stores a single CSAT per session. If the survey is resent, the customer's latest rating replaces the earlier one so your reports stay clean.
  </Accordion>

  <Accordion title="The rating is tied to the contact" icon="user">
    Every submission is linked to the session's contact, so scores roll up against the right person in [Contacts](https://platform.open.cx/contacts) and in CSAT-by-agent reports.
  </Accordion>

  <Accordion title="Custom message" icon="pen-to-square">
    Add a **custom message** on Settings → CSAT to override the default survey prompt. It replaces the default intro line on every enabled channel.
  </Accordion>

  <Accordion title="Instagram and Messenger" icon="triangle-exclamation">
    Not supported yet — the survey won't send on Instagram or Messenger conversations even if other channels are enabled. For social conversations that bridge into the Web Chat widget, enable **Web Chat** as the fallback.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Increase Automation" icon="chart-line" href="/resources/increase-automation">
    Pair low CSAT with handoff reasons to prioritize AI training.
  </Card>

  <Card title="Guaranteed Delivery" icon="paper-plane" href="/resources/guaranteed-delivery">
    Make sure the survey actually reaches the customer.
  </Card>

  <Card title="CSAT API Reference" icon="code" href="/api-reference/csat">
    List, filter, and read scores programmatically.
  </Card>

  <Card title="Contacts" icon="address-book" href="/contacts/manage-contacts">
    See every rating a contact has left, not just the latest.
  </Card>
</CardGroup>

## Feedback after a primary-contact change

When an agent transfers a native email session to another primary contact,
subsequent feedback requests go to the new contact under the existing survey rules.
Use the latest feedback email: links issued before the transfer no longer accept
responses for that session. Previously submitted scores retain their original attribution.


# Guaranteed Message Delivery
Source: https://docs.open.cx/resources/guaranteed-delivery

Our Guaranteed Delivery system makes sure your messages always reach customers - even if they've gone offline or switched devices.

## What's This?

Our Guaranteed Delivery system makes sure your messages always reach customers - even if they've gone offline or switched devices.

<Note>
  Think of it as a smart postal service that always finds the best way to deliver your message!
</Note>

## How It Works

<CardGroup>
  <Card title="Smart Fallback" icon="arrows-split-up-and-left">
    If one channel fails, we automatically try others: - Chat → Email - Phone → SMS + Email - Always
    finds a way through
  </Card>

  <Card title="Unified Tracking" icon="inbox">
    All conversations stay in one place: - Track every message - See delivery status - Monitor
    responses
  </Card>
</CardGroup>

## Common Scenarios

<AccordionGroup>
  <Accordion title="Chat Widget Users">
    When a customer goes offline during chat: - Message saved - Automatically emailed - Chat
    continues when they return
  </Accordion>

  <Accordion title="Phone Conversations">
    After phone calls: - Follow-ups sent via SMS - Backup copy emailed - Multiple channels for
    certainty
  </Accordion>

  <Accordion title="Email Communications">
    For email conversations: - Delivery tracking - Bounce handling - Automatic retries
  </Accordion>
</AccordionGroup>

## Key Features

<Steps>
  <Step title="Automatic Channel Switching">
    System detects when a channel isn't working and switches automatically
  </Step>

  <Step title="Multi-Channel Delivery">
    Uses multiple channels when needed for critical messages
  </Step>

  <Step title="Unified Inbox">All conversations in one place, regardless of channel</Step>

  <Step title="Delivery Confirmation">Track exactly when and how messages are delivered</Step>
</Steps>

## Best Practices

<CardGroup>
  <Card title="Priority Messages" icon="star">
    Use multiple channels for urgent communications
  </Card>

  <Card title="Follow-ups" icon="clock">
    Set automatic follow-up schedules
  </Card>

  <Card title="Channel Selection" icon="sliders">
    Let customers choose their preferred channels
  </Card>

  <Card title="Message History" icon="history">
    Keep track of delivery methods used
  </Card>
</CardGroup>

## Getting Started

Just use our platform normally - Guaranteed Delivery works automatically in the background. No extra setup needed!

<Card title="Need Help?" icon="question">
  Contact our support team at [support@open.cx](mailto:support@open.cx) for assistance with message
  delivery settings.
</Card>


# Increase Automation
Source: https://docs.open.cx/resources/increase-automation

Read the impact report, find where the AI gets stuck, and prioritize the next fix — more knowledge, a new action, or a topic routed to humans.

Your automation rate is the share of conversations the AI resolved on its own. When it plateaus, the fix is almost always one of three things: **missing knowledge**, **missing actions**, or **a topic the AI shouldn't be touching.** The impact report tells you which.

## Read The Report

Open **[Reports → Impact Dashboard](https://platform.open.cx/reports/impact-dashboard)**. The summary shows your automation rate. For the conversations that escalated, open **[Reports → Handoff Insights](https://platform.open.cx/reports/handoff-insights)** — it clusters handoffs by reason so you can see why the AI gave up, not just how often.

## Prioritize The Fix

Work top-down through the reasons. Don't try to fix everything in one pass.

| If most handoffs say... | The fix lives in... |
| - | - |
| *"Couldn't find an answer"* or *"No relevant knowledge"* | [Knowledge sources](/knowledge/sources/overview) — add missing docs, enable a crawler, sync a help center |
| *"Needed to take an action I can't"* — look up order, cancel, refund | [AI Actions](/actions/introduction) — build the endpoint the AI asked for |
| *"Topic should not be handled by AI"* | [Handoff topics](/handoff/topics) — you've already configured this correctly |
| *"Customer asked for a human"* | Nothing to fix — explicit requests are always honored |

## The Cadence

<AccordionGroup>
  <Accordion title="Weekly — skim the summary" icon="calendar-week">
    Five-minute check. Automation rate up or down? Which reason moved most? Log anything surprising.
  </Accordion>

  <Accordion title="Monthly — open the escalated list" icon="calendar-days">
    Read 10–20 escalated conversations end to end. Cluster them by root cause. Each cluster becomes a knowledge update, an action to build, or a topic to add.
  </Accordion>

  <Accordion title="Quarterly — audit the fixes landed" icon="calendar-check">
    Did the automation rate move after you shipped the last round? If not, the fix didn't address the real bottleneck — re-read the escalations before building more.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Knowledge Sources" icon="brain" href="/knowledge/sources/overview">
    Train the AI from docs, help centers, and the web.
  </Card>

  <Card title="AI Actions" icon="bolt" href="/actions/introduction">
    Give the AI real tools to solve real problems.
  </Card>

  <Card title="Handoff Topics" icon="shield-halved" href="/handoff/topics">
    Send specific topics straight to humans.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    The escalation flow every fallback follows.
  </Card>
</CardGroup>


# AI Context Rules
Source: https://docs.open.cx/safety/ai-context

Contacts and sessions can carry custom data — plan type, preferred language, order IDs, and more.

## What's This?

Contacts and sessions can carry custom data — plan type, preferred language, order IDs, and more. AI Context Rules let you control which of those fields the AI can see when crafting responses, helping you balance personalization with data privacy.

## Filtering Modes

<CardGroup>
  <Card title="Allow All" icon="check-double">
    AI sees all custom data fields. Best when no data is sensitive.
  </Card>

  <Card title="Block All" icon="ban">
    No custom data is shared with the AI. Most restrictive.
  </Card>

  <Card title="Allow Only Specific Keys" icon="list-check">
    Only whitelisted keys are visible. Good for selectively sharing relevant fields.
  </Card>

  <Card title="Block Specific Keys" icon="filter">
    All data is shared except blacklisted keys. Good for excluding a few sensitive fields.
  </Card>
</CardGroup>

## How to Configure

<Steps>
  <Step title="Open AI Context Settings">
    Navigate to **Settings → AI Context** in the dashboard.
  </Step>

  <Step title="Choose a Filtering Mode">
    Select a mode for **Contact Custom Data** and/or **Session Custom Data**.
  </Step>

  <Step title="Specify Keys (if applicable)">
    If using "Allow only specific keys" or "Block specific keys", type key names and press Enter to add them.
  </Step>

  <Step title="Save">
    Click **Save** to apply the rules.
  </Step>
</Steps>

## How Custom Data Reaches the AI

* Custom data is attached to contacts (via API or CRM sync) and sessions (via widget, API, or integrations).
* When the AI responds, the filter rules are applied before any data is included.
* Only allowed fields make it into the AI's context.
* Filtered data appears in the AI's system prompt as structured context.

## Default Behavior

<Note>
  By default, no custom data is shared with the AI. You must configure rules to enable it. This ensures sensitive data isn't accidentally exposed.
</Note>

## Passing Custom Data

<CardGroup>
  <Card title="Via Chat Widget" icon="browser" href="/widget/configuration">
    Pass custom data using `sessionCustomData` and context parameters when initializing the widget.
  </Card>

  <Card title="Via API" icon="code" href="/api-reference/contacts/introduction">
    Set contact `custom_data` when [creating contacts](/api-reference/contacts/create), or set session-level `custom_data` when [creating sessions](/api-reference/chat-sessions/create) or with [Send Message](/api-reference/chat-sessions/send).
  </Card>
</CardGroup>


# Understanding AI Decisions
Source: https://docs.open.cx/safety/debug-mode

Debug mode shows you the thinking behind AI responses - what information it used, why it made certain choices, and how it formed its answers.

## What's This?

Debug mode shows you the thinking behind AI responses - what information it used, why it made certain choices, and how it formed its answers.

## Why It's Useful

<CardGroup>
  <Card title="Transparency" icon="glasses">
    See exactly what information the AI used
  </Card>

  <Card title="Training" icon="book">
    Identify knowledge gaps and improvement areas
  </Card>

  <Card title="Quality" icon="star">
    Ensure responses meet your standards
  </Card>

  <Card title="Trust" icon="heart">
    Build confidence in AI decisions
  </Card>
</CardGroup>

## How to Use Debug Mode

<Steps>
  <Step title="Find the Conversation">
    Filter to see AI conversations

    <video />
  </Step>

  <Step title="View AI's Reasoning">
    Click the debug icon to see details

    <video />
  </Step>

  <Step title="Analyze the Components">
    Review three key areas: - **Actions**: Steps the AI took - **Knowledge**: Information sources
    used - **Keywords**: Search terms utilized
  </Step>
</Steps>

## Developer Mode

Need debug info in your widget? Enable it like this:

```javascript theme={"dark"}
initOpenScript({
  // Other options...
  debug: true, // Enables console logs and UI debugging
});
```

<Note>Debug mode in widgets is great for development but should be disabled in production</Note>

Learn more about [widget configuration options](/widget/introduction)


# Real-Time AI Monitoring
Source: https://docs.open.cx/safety/inspect-mode

Real-time monitoring lets you watch AI conversations as they happen. Think of it as looking over the AI's shoulder while it works.

## What's This?

Real-time monitoring lets you watch AI conversations as they happen. Think of it as looking over the AI's shoulder while it works.

## Key Benefits

<CardGroup>
  <Card title="Instant Oversight" icon="eye">
    See every message in real-time
  </Card>

  <Card title="Quick Control" icon="hand">
    Take over instantly if needed
  </Card>

  <Card title="Quality Assurance" icon="check-double">
    Ensure AI responses meet standards
  </Card>

  <Card title="Training Tool" icon="graduation-cap">
    Learn how AI handles different situations
  </Card>
</CardGroup>

## How to Monitor Conversations

<Steps>
  <Step title="Find Active AI Chats">
    Use the AI filter to see ongoing conversations

    <video />
  </Step>

  <Step title="Open the Monitor">
    Click any conversation to start watching

    <img alt="Monitoring View" />
  </Step>

  <Step title="Take Control (If Needed)">Simply type a message to take over from the AI</Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="When to Monitor">
    * New AI deployments - Complex customer issues - High-value conversations - Training periods
  </Accordion>

  <Accordion title="When to Take Over">
    * Complex issues arise - Customer seems frustrated - AI seems uncertain - Sensitive topics come
      up
  </Accordion>
</AccordionGroup>


# AI Safety & Control
Source: https://docs.open.cx/safety/introduction

We understand that using AI for customer interactions needs to be safe and reliable.

## What's This About?

We understand that using AI for customer interactions needs to be safe and reliable. That's why we've built powerful tools to help you:

* Monitor AI conversations in real-time
* Understand AI decisions
* Take control when needed
* Ensure quality responses

## Safety Features

<CardGroup>
  <Card title="Real-Time Monitoring" icon="eye" href="/safety/inspect-mode">
    Watch AI conversations as they happen and jump in if needed
  </Card>

  <Card title="Decision Tracking" icon="magnifying-glass" href="/safety/debug-mode">
    See exactly why the AI responded the way it did
  </Card>

  <Card title="Human Control" icon="user-shield" href="/safety/inspect-mode">
    Take over conversations instantly when needed
  </Card>

  <Card title="Smart Handoff" icon="arrow-right-arrow-left" href="/handoff/introduction">
    AI automatically transfers complex issues to humans
  </Card>
</CardGroup>

## Security & Compliance

<CardGroup>
  <Card title="SOC-2 Certification" icon="certificate">
    In progress (Expected Q4 2024)
  </Card>

  <Card title="Data Security" icon="lock">
    Enterprise-grade security measures
  </Card>
</CardGroup>

Need help setting up safety features? [Contact our team](mailto:support@open.cx)


# PII Redaction
Source: https://docs.open.cx/safety/pii-redaction

Strip card numbers, IBANs, emails, phone numbers, government IDs, and secrets from customer messages as they arrive. Off by default, enabled per organization.

## What's This?

PII redaction detects sensitive values in customer messages **as they arrive** — before the message is saved and before the AI sees it — and replaces each value with a token such as `[CREDIT_CARD_2832]`. It covers chat, email, and live voice transcripts, and images customers send are checked too.

<Note>
  PII redaction is **off by default** and you turn it on per organization. It only affects
  messages that arrive after you enable it. It is not a retention setting: OpenCX never redacts or
  deletes stored sessions because they reached a certain age. To remove data that is already
  stored, see [Data retention](/security/data-retention).
</Note>

## What Gets Protected

Each category has its own switch in the dashboard, so you can redact card numbers but keep email addresses, for example.

| Category | What is detected |
| - | - |
| **Credit Card Numbers** | Credit and debit card numbers, validated so order numbers are not mistaken for cards |
| **Bank Account Numbers (IBAN)** | IBANs from every IBAN country, validated per country |
| **Crypto Wallet Addresses** | Bitcoin and Ethereum wallet addresses, checksum-validated |
| **Email Addresses** | Email addresses in standard formats |
| **Phone Numbers** | International numbers always; numbers written without a country code when you set a default region |
| **Government ID Numbers** | The national identifiers below, plus any number a customer explicitly labels as an ID ("my social security number is…"), even for countries not listed |
| **IP Addresses** | Public IPv4 and IPv6 addresses |
| **API Keys & Secrets** | Pasted API keys, access tokens, and private key blocks |

### Government ID numbers by country

| Country | Identifiers |
| - | - |
| Netherlands | BSN (Burgerservicenummer) |
| Belgium | National Registry Number |
| Germany | Tax ID (Steueridentifikationsnummer) |
| France | Social security number (NIR) |
| Spain | DNI, NIE |
| Portugal | NIF, Citizen Card number |
| Italy | Codice Fiscale |
| Poland | PESEL |
| United Kingdom | National Insurance Number, NHS Number |
| United States | Social Security Number, ITIN |

### How redacted values look

Each value is replaced with a token that keeps a small hint — the last four characters of a number, or the start of an email address — so your team and the AI can refer to "the card ending 2832" without seeing the value. The same value gets the same token throughout a session.

### Images

When redaction is on, images customers send are checked for the categories you enabled. An image that contains one of them, or that looks like a photo of an identity document, is removed, and the AI tells the customer in its next reply and asks them to describe the image in text instead.

If an image cannot be checked, it is removed when storage is set to **Save messages redacted**, and kept when it is set to **Save the original messages**.

## Configuration

<Steps>
  <Step title="Open the PII Redaction settings">
    In the dashboard, go to [**Settings → Security**](https://platform.open.cx/settings/security) and
    find **PII Redaction**. Viewing the section needs the **Redaction** read permission; changing it
    needs **Redaction** write.
  </Step>

  <Step title="Turn on the categories to redact">
    Categories are grouped into **Financial**, **Personal Identifiers**, and **Technical**. Use a
    group's switch to turn all of its categories on or off, or expand the group to switch individual
    categories. Redaction is active as soon as at least one category is on.
  </Step>

  <Step title="Set a default phone region (optional)">
    Under **Phone Numbers**, pick the country used to recognize local numbers written without a
    country code, such as `06 12345678`. International numbers are always recognized, so you can
    leave this on **No region**.
  </Step>

  <Step title="Choose how messages are stored">
    Open **Storage** and pick one:

    * **Save messages redacted** (default) — only the redacted version is saved. The original text is
      never stored and cannot be recovered.
    * **Save the original messages** — the original text is kept alongside the redacted version. The
      AI still only sees redacted text. Teammates with the **Redaction** write permission can reveal
      the original of a message, and every reveal is recorded in the audit log.
  </Step>
</Steps>

## Important Notes

<AccordionGroup>
  <Accordion title="New messages only">
    Redaction runs when a message arrives. Messages stored before you turned it on, and history
    imported from another help desk, are left as they are. To strip content that is already stored,
    use the [Redaction API](/api-reference/redaction/index) or a workflow — see
    [trigger-based removal](/security/data-retention#trigger-based-removal).
  </Accordion>

  <Accordion title="Customer messages only">
    Redaction applies to what customers send. Replies written by your team and by the AI are not
    scanned.
  </Accordion>

  <Accordion title="Save messages redacted is permanent">
    With **Save messages redacted**, the original value is never written to storage, so it cannot be
    restored later — not by your team and not by OpenCX. Switching storage mode or categories only
    affects messages that arrive afterwards.
  </Accordion>
</AccordionGroup>

<Card title="Need Help?" icon="question">
  Contact our security team at [security@open.cx](mailto:security@open.cx) for additional
  redaction patterns or compliance questions.
</Card>


# Audit logs overview
Source: https://docs.open.cx/security/audit-logs

See every sign-in, sign-out and change in your workspace, and who made it. Read this to review access, investigate a change or export the trail.

The audit log records who did what in your workspace, and when. It covers teammate sign-ins and sign-outs, and every change to settings, roles, API keys, AI training, integrations and sessions.

## Who can see it

Only roles with the **Audit logs** permission can open the audit log. The permission is read-only: nobody can edit or delete an entry. The Admin role has it by default. To give it to another role, open **Settings → Roles**, edit the role, and turn on **Audit logs**.

## Open the audit log

Go to **Settings → Security** and scroll to **Audit Logs**. The newest events are at the top, and more load as you scroll.

Each row shows:

* **Actor** — the teammate, API key, Companion, mini-app or automation that acted
* **Event** — what happened, for example *Signed in with Google* or *Updated workflow*
* **Target** — what it happened to. For sign-ins and sign-outs, this is the teammate and the IP address
* **When** — how long ago, and the exact time on hover

Click a row to open its details: the full timestamp, the IP address and device, sign-in details, and a before/after table of what changed.

## Filter the log

Combine any of these filters:

* **Event** — all events, only sign-ins and sign-outs, or one area such as Security or Settings
* **Actor type** — people, the system, or API keys
* **Person** — one teammate: everything they did, plus the sign-outs the system ended for them
* **Date range** — one or more whole days

## Sign-ins and sign-outs

Every time a teammate signs in, the audit log records how they signed in: Google, Microsoft, single sign-on, partner access or password. It also records their IP address and browser.

Every time a teammate stops being signed in, the log records why:

| Reason | What happened |
| - | - |
| Signed out | The teammate signed out |
| Session expired | The sign-in reached its expiry and the teammate had to sign in again |
| Session revoked | The sign-in was ended before it expired |
| Removed from the workspace | An admin removed the teammate, which signs them out everywhere |
| Removed by the identity provider | Your identity provider deprovisioned the teammate |
| Deactivated by the identity provider | Your identity provider deactivated the teammate |

A teammate who belongs to several workspaces shows up in the audit log of each one. Removing a teammate signs them out everywhere: the workspace that removed them sees *Removed from the workspace*, and their other workspaces see *Session revoked*. An expired sign-in is recorded the next time that browser opens the dashboard.

## Read the log over the API

Use [List audit logs](/api-reference/audit-logs/list) to export the trail or feed it into your own security tools. The API key needs the `audit-logs:read` scope. The Companion and the MCP `get_audit_logs` tool read the same log.


# Security Policy
Source: https://docs.open.cx/security/bug-bounty

At Open.cx, we consider the security of our systems a top priority. But no matter how much effort we put into system security, there can still be vulnerabilities present.

Contact: [mo@open.cx](mailto:mo@open.cx)

At Open.cx, we consider the security of our systems a top priority. But no matter how much effort we put into system security, there can still be vulnerabilities present.

If you discover a vulnerability, we would like to know about it so we can take steps to address it as quickly as possible. We would like to ask you to help us better protect our clients and our systems.

## Rewards Program

We may offer rewards for significant security findings. The decision to issue a reward and the reward amount is at Open.cx's sole discretion. Rewards are typically based on:

* Severity and impact of the vulnerability
* Quality and clarity of the report
* Potential for exploitation
* Affected customer base

Note that not all valid reports will qualify for a reward. We reserve the right to modify or terminate this program at any time without prior notice.

## Out of Scope Vulnerabilities

* Clickjacking on pages with no sensitive actions
* Unauthenticated/logout/login CSRF
* Attacks requiring MITM or physical access to a user's device
* Any activity that could lead to the disruption of our service (DoS)
* Content spoofing and text injection issues without showing an attack vector/without being able to modify HTML/CSS
* Email spoofing
* Missing DNSSEC, CAA, CSP headers
* Lack of Secure or HTTP only flag on non-sensitive cookies
* Deadlinks

## Reporting Guidelines

Please do the following:

1. E-mail your findings to [mo@open.cx](mailto:mo@open.cx)
2. Do not run automated scanners on our infrastructure or dashboard. If you wish to do this, contact us and we will set up a sandbox for you
3. Do not take advantage of the vulnerability or problem you have discovered, for example by downloading more data than necessary to demonstrate the vulnerability or deleting or modifying other people's data
4. Do not reveal the problem to others until it has been resolved
5. Do not use attacks on physical security, social engineering, distributed denial of service, spam or applications of third parties
6. Do provide sufficient information to reproduce the problem, so we will be able to resolve it as quickly as possible. Usually, the IP address or the URL of the affected system and a description of the vulnerability will be sufficient, but complex vulnerabilities may require further explanation

## Our Commitment

What we promise:

1. We will respond to your report within 3 business days with our evaluation of the report and an expected resolution date
2. If you have followed the instructions above, we will not take any legal action against you in regard to the report
3. We will handle your report with strict confidentiality, and not pass on your personal details to third parties without your permission
4. We will keep you informed of the progress towards resolving the problem
5. In the public information concerning the problem reported, we will give your name as the discoverer of the problem (unless you desire otherwise)
6. We strive to resolve all problems as quickly as possible, and we would like to play an active role in the ultimate publication on the problem after it is resolved


# Data retention policy
Source: https://docs.open.cx/security/data-retention

How long OpenCX keeps each category of data, what triggers disposal, and how a deletion request reaches every store that holds a copy.

Retention is a security control, not a storage setting. Data that no longer serves a purpose is
liability without upside — so OpenCX defines a rule for every category of information, a trigger
that starts disposal, a method that carries it out, and a record proving it happened.

This page is the customer-facing summary of the Open Data Management & Retention Policy, owned
by the CTO/CISO and reviewed annually. It aligns with ISO/IEC 27001:2022 controls A.5.33, A.8.10
and A.8.12, SOC 2 criteria C1.1–C1.2 and P4.1–P4.3, and the storage-limitation principle in GDPR
Article 5(1)(e).

<Note>
  Your data stays with you for as long as you are a customer. OpenCX runs **no scheduled job that
  deletes or redacts customer data after a fixed age** — removal happens when you ask for it, when a
  workflow you built fires, or when your account is terminated. Where your contract with OpenCX
  defines a retention or deletion term, **your contract governs**.
</Note>

## Principles

<CardGroup>
  <Card title="Data minimisation" icon="filter">
    Information is retained only where there is a defined business, contractual, or legal purpose
    for keeping it.
  </Card>

  <Card title="Storage limitation" icon="hourglass-half">
    Retention is bounded by the purpose. When the purpose ends, the clock starts.
  </Card>

  <Card title="Auditable disposal" icon="clipboard-check">
    Every deletion produces a verifiable record — what was requested, what was executed, against
    which stores, by whom, and when.
  </Card>

  <Card title="Reviewed, not forgotten" icon="clipboard-list">
    Data storage systems are reviewed quarterly and the full data inventory annually. Nothing is
    held without someone owning the reason.
  </Card>
</CardGroup>

## Retention schedule

<RetentionScheduleChart />

The same schedule in full, including the event that starts the retention clock and the method used
to dispose of the data:

| Category | Classification | Retention | Retention trigger | Disposal method |
| - | - | - | - | - |
| Session data (messages, transcripts, metadata) | Confidential | Retained while your account is in good standing. At least 30 days after termination, so you can bring the account back. Deleted within 30 days of a deletion request. | Account termination or deletion request | Scoped hard deletion in the production database — cascading where the schema defines a cascade, explicit cleanup where it does not |
| Attachments & exports | Confidential | Same as session data | Account termination or deletion request | Metadata removed, then a permanent object-removal request to our storage service; failures logged and followed up |
| Knowledge base content | Confidential | Same as session data | Account termination, deletion request, or source removal | Scoped hard deletion in the production database |
| Search & reporting derivatives | Confidential | Deleted with the records they were built from | Deletion of the source record | Tombstoned, excluded from reads immediately, physically removed as the store merges |
| Recovery backups | Confidential | Bounded recovery window | Expiry of that window | Backups age out on their own schedule; individual records are never selectively removed from an existing backup |
| System & application logs | Internal | Held only as long as they serve operations and security | Age | Expiry from the logging store |
| Audit logs & security records | Confidential | At least 5 years | Regulatory / audit cycle | Secure deletion after retention |
| Billing & financial records | Confidential | 7 years | Tax / legal obligations | Secure deletion after retention |
| Marketing & prospect data | Internal | Until the contact opts out, asks for erasure, or the relationship lapses | Opt-out, inactivity, or data-subject request | Secure deletion |

<Tip>
  **Derivatives never outlive their source.** The search and reporting copies built from your
  content are Confidential too. Deleting a record tombstones its derivatives in the same operation —
  they drop out of every read immediately, and the bytes go when the store next merges.
</Tip>

## Lifecycle

Every asset carries a classification and a retention rule from the moment it is created. Disposal is
a controlled operation, not a background timer: a trigger fires — an account termination, a deletion
request, a workflow you built — an engineer executes the removal against every store that holds a
copy, and each leg is verified before the request is closed.

<RetentionLifecycleFlow />

## Trigger-based removal

Retention does not have to wait on a calendar. Often the right moment to strip a session is the
moment it stops being operationally useful — the session closed, the case was resolved in your
ticketing system, the thread went cold. **Workflows** let you bind removal to that event.

The pattern is the same in every case: a trigger fires, a workflow runs, and the workflow calls
[`POST /redaction/session`](/api-reference/redaction/redact-session) to strip the session's messages
and attachments.

<Tabs>
  <Tab title="Ticket closed in your ticketing system">
    When an agent closes the ticket in Zendesk, Salesforce, HubSpot, or any connected ticketing
    system, the webhook closes the matching OpenCX session and fires the **`ticket-resolved`**
    trigger. Hang a workflow off it to remove the transcript as soon as the system of record says
    the work is done.

    <Steps>
      <Step title="Trigger: Ticket resolved">
        Fires on close in OpenCX **and** on close propagated from the connected ticketing system.
      </Step>

      <Step title="Optional: Wait">
        Add a **Wait** step for a cooling-off period — long enough to absorb a reopen, short enough
        that the transcript is not sitting around. A common choice is 7 days.
      </Step>

      <Step title="Optional: Condition">
        Branch on tags, team, or channel so removal only applies where you want it — for example
        sessions tagged `payments` but not those tagged `dispute`.
      </Step>

      <Step title="Action: Redact the session">
        An **HTTP call** step to `POST /redaction/session` with the session id from the trigger
        context. The API key needs the `redaction:write` scope.
      </Step>
    </Steps>

    <Warning>
      Redaction is irreversible. Put the reopen window before the removal step, not after — a
      session stripped the instant a ticket closes has no transcript left if the customer replies an
      hour later and the ticket reopens.
    </Warning>
  </Tab>

  <Tab title="Session went inactive">
    The **`ticket-inactive`** trigger fires when a session has had no activity for a configured
    period. Use it to catch sessions that were never formally closed — abandoned chats, one-message
    threads, bot-only sessions — which otherwise sit at full fidelity for as long as you hold them.

    Pair it with a condition on message count or channel so you only sweep the genuinely
    low-value ones.
  </Tab>

  <Tab title="Tag-driven removal">
    The **`ticket-tag-added`** trigger turns removal into a one-click action for your agents. Add a
    tag such as `erasure-request` to a session and the workflow strips it immediately — useful when
    a customer asks for erasure mid-session and you want the agent to action it without escalating
    to your security team.

    Gate this one carefully: anyone who can tag a session can trigger deletion. Restrict the tag to
    a role that should hold that power.
  </Tab>

  <Tab title="Scheduled sweep">
    A **`cron-trigger`** workflow runs on your schedule — nightly, weekly — and applies a rule no
    static schedule could express. For example: strip sessions from a specific channel after 14
    days, or remove test and internal sessions on a much shorter cycle than customer sessions.

    Age-based removal is available to you here, and only here: **you** define the rule and own the
    schedule. OpenCX runs no age-based sweep over your data on your behalf.
  </Tab>
</Tabs>

<Note>
  **There is no automatic redaction window.** Nothing in OpenCX strips a session because it reached
  a certain age. Two real controls sit either side of that gap. **PII redaction at ingest** is an
  opt-in, per-organisation setting — off until you turn it on — that detects and strips sensitive
  values from chat, email, and live voice transcripts *as messages arrive*, in either **redact at
  rest**, where the original is never stored, or **preserve original**, where the original stays
  retrievable behind the `redaction:write` permission and every reveal is audit-logged. **Redaction
  on demand** is the [`POST /redaction/session`](/api-reference/redaction/redact-session) and
  [`POST /redaction/message`](/api-reference/redaction/redact-message) endpoints, called by hand or
  by the workflows above, for anything already stored.
</Note>

## Disposal methods

<AccordionGroup>
  <Accordion title="Scoped hard deletion" icon="database">
    The primary method for your records in the production database. Deletion is scoped to exactly
    the rows in the request — cascading to dependents where the schema defines a cascade, with
    explicit cleanup where it does not. There is no soft-delete flag left behind; the rows are gone.

    Org-level deletion is coordinated by an engineer, executed against every table that holds a
    copy, and verified before the request is closed.
  </Accordion>

  <Accordion title="Permanent object removal" icon="box-archive">
    For files — attachments, exports, call recordings. The metadata record is deleted and a
    permanent object-removal request is issued to our storage service. Org-level deletion enumerates
    every attachment, export, and recording explicitly rather than trusting a prefix sweep, and any
    removal that fails is logged and followed up until the object is confirmed gone.
  </Accordion>

  <Accordion title="Tombstones in derived stores" icon="layer-group">
    The search and reporting stores do not support row-level deletes. A deletion writes a tombstone
    instead: the record is excluded from every read the moment the tombstone lands, and the bytes
    are physically removed as the store merges its data files.
  </Accordion>

  <Accordion title="Backups" icon="clock-rotate-left">
    Individual records are **not** selectively removed from an existing recovery backup — residual
    copies can persist until the recovery window expires and the backup ages out on its own. If a
    backup is ever restored, the deletion is reapplied before the system returns to service.
  </Accordion>

  <Accordion title="Physical media" icon="hard-drive">
    OpenCX operates no customer-facing physical media. Corporate endpoints are full-disk encrypted;
    on retirement the disk is cryptographically erased through device management and the hardware is
    wiped or physically destroyed by a contracted provider under certificate of destruction.
  </Accordion>

  <Accordion title="Evidence of disposal" icon="file-check">
    Every deletion request produces a record: what was requested, what was executed, against which
    stores, by whom, and when. Data storage systems are reviewed quarterly, the full data inventory
    annually, and backups are tested annually for integrity.
  </Accordion>
</AccordionGroup>

## Deletion requests

A deletion request is not a single `DELETE`. A copy of a record can exist in the production
database, in object storage, in derived search and reporting stores, in backups, and at a
sub-processor — so the request fans out to every one of them and is confirmed only when the last
live leg completes.

<DeletionCascadeFlow />

**Where OpenCX is a Processor** — your customer data — ask us and all data we have no legal or
business obligation to retain is deleted **within 30 days**. The request runs against the production
database, object storage, the derived search and reporting stores, and the relevant sub-processors,
and each leg is verified before the request is closed. Backups are the stated exception: they are
not selectively edited, they age out on their own schedule, and a restored backup has the deletion
reapplied before it returns to service.

**Where OpenCX is a Controller** — employee and prospect data — data-subject requests are logged,
authenticated, actioned, and confirmed in writing to the requester under applicable data-protection
law.

<Card title="Submit a deletion or data-subject request" icon="envelope" href="mailto:help@open.cx">
  Email [help@open.cx](mailto:help@open.cx). Include the org, the scope of data, and the legal basis
  if the request is made on behalf of a data subject.
</Card>

## Legal holds & exceptions

A legal hold suspends normal retention and disposal for specified data until the hold is released.

<Steps>
  <Step title="Initiated by an authorised party">
    Only the CEO, the CTO/CISO, or General Counsel may place a hold.
  </Step>

  <Step title="Documented in writing">
    Scope and justification are recorded before the hold takes effect.
  </Step>

  <Step title="Reviewed at least every six months">
    Holds are re-justified or released — they do not become permanent by neglect.
  </Step>
</Steps>

Exceptions to the schedule — for example extended retention for a specific category — require
written CTO/CISO approval, are recorded in the GRC platform, and are subject to periodic review.

## Sub-processors

Sub-processors are contractually required to meet retention periods and disposal rules **at least as
strict** as those above. Compliance is verified annually under the Vendor Management Policy, and on
any change of scope.

## Governance

| Role | Responsibility |
| - | - |
| CTO / CISO | Owns the policy, approves exceptions, authorises legal holds, escalates breaches |
| Data Protection Officer | Data-protection compliance, data-subject rights, sub-processor agreements |
| Engineering | Executes and verifies deletion requests across every store, maintains disposal records |
| Asset owners | Identify applicable periods for their assets and sign off on disposal |
| People Operations | Employee and contractor records, in line with employment law |
| All personnel | Apply classification and never retain data beyond its defined period |

## Retention you control

You can hold less than the schedule allows, without a contract change. These controls are yours, set
per organisation:

<CardGroup>
  <Card title="PII redaction" icon="user-shield" href="/safety/pii-redaction">
    Opt in and sensitive values are stripped from chat, email, and live voice as messages arrive —
    per category, in redact-at-rest or preserve-original mode.
  </Card>

  <Card title="Workflow-driven removal" icon="bolt" href="#trigger-based-removal">
    Bind removal to a session closing, going inactive, or picking up a tag — or to a schedule you
    define.
  </Card>

  <Card title="Connect thread lifecycle" icon="timer" href="/connect/threads">
    Grace and retention windows for Connect threads are set per org, and per thread at creation.
  </Card>
</CardGroup>

<Info>
  Enterprise customers can request the full signed Data Management & Retention Policy, the
  sub-processor register, and disposal evidence samples as part of a security review. Contact
  [security@open.cx](mailto:security@open.cx).
</Info>


# Single sign-on (SSO)
Source: https://docs.open.cx/security/sso/overview

Let your team sign in to OpenCX through your identity provider — Okta, Microsoft Entra ID, Google Workspace, or any SAML 2.0 / OIDC IdP — with self-serve setup, just-in-time provisioning, and SCIM 2.0 directory sync.

Let your team sign in to OpenCX through your own identity provider, using SAML 2.0 or OpenID Connect.

<Note>
  SSO is self-serve: an admin with settings permissions configures it at [**Settings → Security**](https://platform.open.cx/settings/security). No OpenCX involvement required.
</Note>

## Overview

We support most identity providers (Okta, Microsoft Entra ID, Google Workspace, OneLogin, JumpCloud, Auth0, Keycloak, AD FS, etc.) over SAML 2.0 or OIDC.

Members sign in by clicking **Sign in with SSO** on [platform.open.cx](https://platform.open.cx) and entering their work email — OpenCX matches the domain to your provider and redirects to your IdP.

Each provider is bound to one email domain, verified with a DNS record before sign-ins work. Working with multiple domains? Add a provider per domain.

Directory sync sits on top: [SCIM provisioning](#scim-provisioning) creates accounts when you assign users in your IdP and cuts off access when you unassign them, instead of waiting for a sign-in attempt.

## Configure

1. Navigate to [**Settings → Security**](https://platform.open.cx/settings/security) and click **Add provider**.
2. Pick **SAML** or **OIDC** and fill in the form. For SAML you'll paste your IdP's **metadata XML** and its **entity ID**; for OIDC, the **issuer URL**, **client ID**, and **client secret**. Every provider needs the **email domain** your team signs in with.
3. OpenCX generates your provider's IdP-facing values at creation, so create the app in your IdP with placeholder URLs first, then replace them with the real values shown on the provider card — **Reply URL (ACS)** and **Identifier (Entity ID)** for SAML, or **Redirect URI** for OIDC. Each value has a copy button.
4. Click **Set up DNS** on the provider card, publish the TXT record it shows, then click **Verify domain**. Sign-ins for the domain are rejected until this passes — see [Domain verification](#domain-verification).

<Note>
  Provider configuration can't be edited after creation. To rotate a certificate or client secret — or change anything else — delete the provider and add it again. This generates a new provider ID, so update your IdP app's URLs and re-verify the domain in the same change.
</Note>

### Okta

* [Okta documentation](https://support.okta.com/help/s/article/How-To-Configure-A-Custom-SAML-App)
* In the Okta Admin console, navigate to **Applications → Create App Integration → SAML 2.0** and name the app.
* Set **Name ID format** to **EmailAddress** and **Application username** to **Email** — OpenCX identifies members by email.
* From the app's **Sign On** tab, open **View IdP metadata** and paste the XML into OpenCX. The metadata's `entityID` is your **IdP entity ID**.
* Enter OpenCX's **Reply URL (ACS)** as the **Single sign-on URL** in Okta, and **Identifier (Entity ID)** as the **Audience URI**, then assign users to the app.

### Microsoft Entra ID

Entra works over both protocols: **SAML** via an enterprise application, or **OIDC** via an app registration. It works even if your email is hosted elsewhere (e.g. Google Workspace).

**SAML** — [Entra ID documentation](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal)

* From Microsoft Entra ID, select **Enterprise Applications → New application → Create your own application** (non-gallery), then **Single sign-on → SAML**.
* Edit **Attributes & Claims** and set the **Unique User Identifier (Name ID)** to **Email address** format, source `user.mail`. If `user.mail` is empty (cloud-only users without a mailbox), fill the user's **Mail** attribute — or use `user.userprincipalname`, but only when all members' UPNs are on your email domain (the default UPN breaks guest users, see [FAQ](#faq)).
* Download the **Federation Metadata XML** (SAML Certificates section) and paste its contents into OpenCX. Your **IdP entity ID** is the **Microsoft Entra Identifier** (`https://sts.windows.net/<tenant-id>/`), also the metadata's `entityID`.
* Enter OpenCX's values in **Basic SAML Configuration** — the field names match the provider card.
* Assign users or groups under **Users and groups** — unassigned users get `AADSTS50105` at sign-in.

**OIDC**

* From **App registrations → New registration**, create a single-tenant app. Under **Authentication → Add a platform → Web**, set OpenCX's **Redirect URI** from the provider card. Leave both implicit-grant checkboxes unchecked — OpenCX uses the authorization-code flow.
* Under **Certificates & secrets**, create a client secret and copy its **Value** (shown only once) — not the Secret ID.
* Your **issuer URL** is `https://login.microsoftonline.com/<tenant-id>/v2.0`.
* Under **Token configuration**, add the optional **email** claim to the ID token — the user's email must be on your verified domain (the guest-user caveat above applies here too).

### Google Workspace

* [Google documentation](https://support.google.com/a/answer/6087519)
* In the Admin console, navigate to **Apps → Web and mobile apps → Add app → Add custom SAML app**.
* Download the metadata on the **Google Identity Provider details** step and paste its contents into OpenCX. Set **Name ID** to **Primary email**, format **EMAIL**.
* Enter OpenCX's **Reply URL (ACS)** as the **ACS URL** and **Identifier (Entity ID)** as the **Entity ID**.
* Turn the app **ON** for the organizational units that need access — Google apps default to OFF, and changes can take a while to propagate.

### Other SAML providers

* Any standards-compliant SAML 2.0 IdP works — OneLogin, JumpCloud, Ping, Duo, Auth0, on-prem AD FS. Export the app's metadata XML and paste it into OpenCX.
* The **Name ID must be the user's email** (format `emailAddress`), and the response must be **signed** — unsigned assertions are rejected. Sign with **SHA-256 or better**: old AD FS installs default to SHA-1, so change the relying party trust's secure hash algorithm.
* Keep the IdP host NTP-synced: assertions outside their timestamp validity window are rejected.
* OpenCX's **Identifier (Entity ID)** URL serves standard SP metadata XML — IdPs that import SP metadata can consume it directly.

### OIDC providers

* Create a **web application** (confidential client) using the **authorization-code** grant, with the `openid`, `email`, and `profile` scopes. The ID token must carry an `email` claim.
* The **issuer URL** must be HTTPS and publicly reachable; OpenCX validates its discovery document (`{issuer}/.well-known/openid-configuration`) when you add the provider. A **Discovery endpoint** field is available if yours lives elsewhere.
* Enter OpenCX's **Redirect URI** as the client's allowed callback URL — it must match exactly.
* Client secrets expire — note the date, and re-add the provider with a fresh secret before it lapses.

## Just-in-time provisioning

When someone signs in through your IdP for the first time, OpenCX creates their account and adds them to your organization. Sign-ins with an email that isn't on your verified domain are rejected, with the reason shown on the sign-in page.

**Set during account creation:**

* **Email**: the SAML Name ID or OIDC `email` claim. This is the identity key — OpenCX matches sign-ins to members by email.
* **Name**: taken from your IdP's name attributes or the `name` claim.
* **Role**: the **SSO Member** role, auto-created in your organization the first time it's needed. It grants read-only access to conversations and nothing else.

Later sign-ins never update the member — in particular, SSO never changes roles. To give someone more access, assign a role at [**Settings → Teammates**](https://platform.open.cx/settings/teammates); to change what all future SSO users get, edit the SSO Member role at [**Settings → Roles**](https://platform.open.cx/settings/roles).

<Note>
  Anyone with an email on your verified domain can join your organization by signing in through your IdP, so the SSO Member role's permissions are what "anyone at the company" gets on day zero. Keep it lean and escalate per person.
</Note>

## Domain verification

Each provider shows a DNS challenge under **Set up DNS** on its card:

| Field | Value |
| - | - |
| Type | `TXT` |
| Name | `_opencx-sso-challenge.acme.com` |
| Value | `opencx-domain-verification=<your-provider-token>` |

Publish the record in your DNS zone, then click **Verify domain**. The token is stable for the life of the provider, so leave the record in place and retry while DNS propagates. Verification is what stops anyone else from wiring SSO for a domain they don't own.

## SCIM provisioning

SCIM 2.0 keeps OpenCX in sync with your directory: assigning a user in your IdP creates their OpenCX account, and unassigning or disabling one revokes their access on the next sync cycle. It complements SSO rather than replacing it — sign-in still runs through your provider.

SCIM requires an SSO provider with a **DNS-verified domain** on the same organization. It never creates users on a domain you haven't verified — those attempts fail with `scim_domain_not_verified` in your IdP's provisioning log.

1. Navigate to [**Settings → Security**](https://platform.open.cx/settings/security), find **SCIM provisioning**, and click **Set up SCIM**.
2. Copy the **Tenant URL** (`https://api.open.cx/backend/auth/scim/v2`) and the **secret token**.
3. Paste both into your IdP's provisioning configuration — see [Entra ID provisioning](#entra-id-provisioning) below.

<Note>
  The token is shown exactly once. If you lose it, rotate it from the same card — rotating invalidates the old token immediately, and already-provisioned users stay linked, so your IdP keeps managing the same people without re-creating anyone.
</Note>

### What syncs

Users only. Group and role sync aren't supported — roles are assigned in OpenCX.

**Create and assign** — OpenCX creates the account with its email pre-verified and adds it to your organization with the **SSO Member** role, the same least-privilege default that [SSO sign-in](#just-in-time-provisioning) grants. If the person already exists — invited earlier, or signed in through SSO before — SCIM links to that account instead of creating a second one, and leaves their existing roles alone. SCIM never downgrades anyone. Upgrade access per person at [**Settings → Teammates**](https://platform.open.cx/settings/teammates).

**Deactivate (`active: false`)** — unassigning or disabling the user in your IdP bans them, revokes every live session immediately, and blocks sign-in. Organization membership and roles are preserved, so flipping them back to `active: true` restores the person exactly as they were.

**Delete** — a hard delete removes the person from your workspace: membership and the SCIM link go away and sessions are revoked, but their conversation history is preserved. Delete doesn't ban — deactivation is the tool for blocking access, and Entra always deactivates before it deletes.

<Note>
  Deactivation is platform-wide, not per-workspace. If the same person belongs to more than one OpenCX workspace, deactivating them in your IdP blocks their sign-in everywhere — the IdP owns the identity.
</Note>

### Entra ID provisioning

* [Entra ID documentation](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/user-provisioning)
* From **Enterprise applications**, open the same app you use for SSO — or create a new non-gallery app — then select **Provisioning → New configuration**.
* Set the mode to **Automatic**, paste the **Tenant URL** and **Secret Token** from the OpenCX dashboard, and click **Test Connection**.
* Under **Mappings**, the defaults work: `userName` must map to the user's email (`userPrincipalName`), and `externalId` to `objectId`. Provision **Users** only — disable the Groups mapping, which OpenCX doesn't support.
* Set **Scope** to **Sync only assigned users and groups**, then assign the users and groups to provision under **Users and groups**.
* Turn provisioning **On**. Entra's sync cycle runs roughly every 40 minutes, so creates and deactivations land on that cadence — offboarding takes effect at sync time rather than waiting for the user's next sign-in attempt, as it does with SSO alone.

<Note>
  Provisioning failures appear in the app's **Provisioning logs** with the OpenCX error detail. `scim_domain_not_verified` means the user's email domain isn't a DNS-verified SSO domain on your workspace — with Entra this is usually a guest user, whose UPN is the `name_domain#EXT#@tenant.onmicrosoft.com` form rather than their real address. Legacy tenants that send `active` as the string `"False"` are handled, so no workaround is needed there.
</Note>

### Okta provisioning

Okta takes the same two values: in the app's **Provisioning** tab, set the **SCIM connector base URL** to the Tenant URL and **Authentication Mode** to **HTTP Header**, with the OpenCX token as the bearer token.

## Offboarding

With [SCIM](#scim-provisioning) connected, disabling or unassigning a user in your IdP revokes their OpenCX sessions and cuts off their access on the next sync cycle — no dashboard step needed.

Without SCIM, disabling a user in your IdP only blocks their next SSO sign-in. It doesn't end active OpenCX sessions or remove their membership — for immediate, complete removal, also remove them at [**Settings → Teammates**](https://platform.open.cx/settings/teammates).

## FAQ

<AccordionGroup>
  <Accordion title="Sign-in says 'No SSO is configured for this email domain'">
    The email's domain didn't resolve to a verified provider. Check that the provider isn't still **Pending verification**, that the user's email domain matches the provider's domain exactly (`acme.io` ≠ `acme.com`), and that the provider wasn't deleted.
  </Accordion>

  <Accordion title="'Verify domain' says the DNS record isn't found">
    DNS propagation usually takes minutes but can take longer. Confirm the record with `dig TXT _opencx-sso-challenge.acme.com +short` — the output must contain the exact value from the dashboard. Common mistakes: the record sits at the zone apex instead of the `_opencx-sso-challenge` host, the value has extra quotes or whitespace, or it's in the wrong DNS zone.
  </Accordion>

  <Accordion title="The sign-in fails after redirecting to my IdP">
    The sign-in page shows the failure reason after the redirect back. Usual causes: the IdP app still holds placeholder URLs from initial setup (paste in the values from the provider card), the user isn't assigned to the app in your IdP, the SAML response is unsigned, or your IdP rotated its signing certificate since the provider was added (delete and re-add with fresh metadata).
  </Accordion>

  <Accordion title="A new user bounced back to the sign-in page instead of being provisioned">
    Your IdP returned an email that isn't on your verified domain, so provisioning refused to create the account — the sign-in page shows the rejection. With Entra this is usually a guest user: their default Name ID is the `name_domain#EXT#@tenant.onmicrosoft.com` UPN, not their real address. Point the Name ID (SAML) or email claim (OIDC) at `user.mail`, or make them a tenant member with a UPN on your domain.
  </Accordion>

  <Accordion title="OIDC: redirect_uri_mismatch or invalid_client">
    `redirect_uri_mismatch` means the client's callback URL doesn't exactly match the **Redirect URI** on the provider card. `invalid_client` means wrong credentials or an expired client secret — re-add the provider with a fresh one.
  </Accordion>

  <Accordion title="Duplicate accounts appear on re-login">
    Your IdP is sending a directory identifier (like Entra's object ID) as the SAML Name ID instead of the email. Set the Name ID to email format.
  </Accordion>

  <Accordion title="Why can new SSO users only view conversations?">
    That's the [SSO Member role](#just-in-time-provisioning) — the deliberate least-privilege default. Assign bigger roles per person at **Settings → Teammates**, or edit the role itself at **Settings → Roles**.
  </Accordion>

  <Accordion title="SCIM: 'Test Connection' fails in my IdP">
    Check that the **Tenant URL** ends in `/scim/v2` and that the token is pasted whole — it's a single opaque string with no `Bearer ` prefix. A token that was rotated after you pasted it no longer works; rotate again and update the IdP with the new value.
  </Accordion>

  <Accordion title="SCIM: provisioning log shows 'scim_domain_not_verified'">
    The user's email domain isn't a DNS-verified SSO domain on your workspace, so SCIM refused to create the account. Verify the domain under [**Settings → Security**](https://platform.open.cx/settings/security) — see [Domain verification](#domain-verification) — or add a provider for the domain those users are on. With Entra, guest users hit this because their UPN is on `tenant.onmicrosoft.com`.
  </Accordion>

  <Accordion title="SCIM: can it sync groups or roles?">
    No — SCIM provisions users only. Everyone lands in the [SSO Member role](#just-in-time-provisioning); assign bigger roles per person at **Settings → Teammates**. Disable the Groups mapping in your IdP.
  </Accordion>

  <Accordion title="SCIM: I lost the token">
    Rotate it under **Settings → Security**. The old token stops working immediately, and users already provisioned stay linked — paste the new token into your IdP and provisioning resumes where it left off.
  </Accordion>

  <Accordion title="Can members still sign in with Google or Microsoft?">
    Yes. SSO doesn't disable the other sign-in buttons or enforce IdP-only sign-in.
  </Accordion>

  <Accordion title="Can members sign in from the app tile in our IdP dashboard?">
    No — sign-in starts at [platform.open.cx](https://platform.open.cx) with **Sign in with SSO**. IdP-initiated sign-in isn't supported.
  </Accordion>
</AccordionGroup>

Still stuck? Send the failing user's email, the approximate time, your IdP, and any IdP-side error code to [support@open.cx](mailto:support@open.cx).


# US Number Compliance
Source: https://docs.open.cx/sms/compliance

10DLC and toll-free registration requirements for US phone numbers — what to prepare, how to register, and what happens without it.

<Warning>
  US carriers **silently block** outbound SMS from unregistered numbers. You must complete registration before going live.
</Warning>

<Tip>
  For setup steps, see [Connect SMS](/sms/connect-sms). For troubleshooting, see [Troubleshooting](/sms/troubleshooting).
</Tip>

## Which Numbers Need Registration?

<CardGroup>
  <Card title="US Local Numbers" icon="flag">
    Any US **+1** number that is **not** toll-free. Requires <Tooltip>**10DLC registration**</Tooltip> before outbound messages can be delivered.
  </Card>

  <Card title="US Toll-Free Numbers" icon="phone">
    Prefixes **+1800, +1833, +1844, +1855, +1866, +1877, +1888**. Exempt from 10DLC but requires separate <Tooltip>**toll-free verification**</Tooltip>.
  </Card>
</CardGroup>

## Required Data

Gather the following before starting registration.

<AccordionGroup>
  <Accordion title="Brand registration (business identity) — 10DLC" icon="building">
    | Field | Detail |
    | - | - |
    | **Legal business name** | Exact name as registered with your EIN. Must match your IRS CP 575 confirmation letter. |
    | **EIN** | 9-digit Employer Identification Number (format: XX-XXXXXXX). Canadian businesses use their Canadian Business Number instead. |
    | **Business address** | Registered address on file with your tax agency. |
    | **Business type** | Industry category (e.g. Technology, Professional Services, Retail). |
    | **Business contact email** | Used for identity verification (2FA). |
    | **Website** | Your company website URL. |

    <Note>Sole proprietors without an EIN register as a **Sole Proprietor Brand** using first/last name instead. Sole proprietors with an EIN must register as a Standard or Low-Volume Brand.</Note>
  </Accordion>

  <Accordion title="Campaign registration (messaging use case) — 10DLC" icon="bullhorn">
    | Field | Detail |
    | - | - |
    | **Use case** | What you send texts for (e.g. customer support, order notifications, appointment reminders). |
    | **Description** | A short summary of your messaging program. |
    | **Sample messages** | 2–5 example messages your customers would receive. |
    | **Opt-in flow** | How customers agree to receive texts (e.g. checkbox on your website, keyword opt-in). |
    | **Privacy policy URL** | Public link to your privacy policy. **Required for all new campaigns.** |
    | **Terms & conditions URL** | Public link to your terms of service. **Required for all new campaigns.** |
  </Accordion>

  <Accordion title="Toll-free verification" icon="phone">
    | Field | Detail |
    | - | - |
    | **Business name** | Your legal business name. |
    | **EIN** | 9-digit Employer Identification Number (format: XX-XXXXXXX). Required for all business types except sole proprietors. |
    | **Business type** | One of: Private Profit, Public Profit, Non-Profit, Government, or Sole Proprietor. |
    | **Website** | Your company website URL. |
    | **Use case category** | Why you send texts (e.g. customer care, account notifications). |
    | **Use case summary** | A short description of your messaging program. |
    | **Sample message** | An example outbound message. |
    | **Opt-in type** | How customers consent (e.g. verbal, web form, keyword). |
    | **Estimated message volume** | Monthly volume estimate. |
    | **Privacy policy URL** | Public link to your privacy policy. |
  </Accordion>
</AccordionGroup>

## Registration Steps

Registration is handled by the OpenCX team on your behalf. Gather the required data above, then follow the steps below.

<Tabs>
  <Tab title="10DLC">
    <Steps>
      <Step title="Buy Or Verify Your Number">
        Go to **[Settings → Phone Numbers](https://platform.open.cx/settings/phone-numbers)**. Buy a US local number from inventory or verify a number you already own.
      </Step>

      <Step title="Prepare Your Brand And Campaign Data">
        Collect the fields listed in the **Brand registration** and **Campaign registration** sections above. You will need your EIN, legal business name, use case, sample messages, and policy URLs.
      </Step>

      <Step title="Contact The OpenCX Team">
        Reach out to your account team or contact support from your [OpenCX dashboard](https://platform.open.cx). Provide the brand and campaign data. The team submits your registration to US carriers.
      </Step>

      <Step title="Wait For Approval">
        Brand review typically takes a few business days. Campaign review takes **10–15 business days**. You will be notified when approved.
      </Step>

      <Step title="Enable SMS">
        Once approved, go to **[Channels → SMS](https://platform.open.cx/channels/sms)**, select your registered number, and enable the channel.
      </Step>
    </Steps>

    <Warning>
      The [SMS channel page](https://platform.open.cx/channels/sms) shows a blocking warning when a US local number is selected without 10DLC registration. Outbound texts will not be delivered until registration is complete.
    </Warning>
  </Tab>

  <Tab title="Toll-free verification">
    <Steps>
      <Step title="Buy Or Verify Your Toll-Free Number">
        Go to **[Settings → Phone Numbers](https://platform.open.cx/settings/phone-numbers)**. Buy a US toll-free number (+1800, +1833, +1844, +1855, +1866, +1877, or +1888) or verify one you already own.
      </Step>

      <Step title="Prepare Your Verification Data">
        Collect the fields listed in the **Toll-free verification** section above. You will need your business name, EIN, use case, sample messages, opt-in proof, and privacy policy URL.
      </Step>

      <Step title="Contact The OpenCX Team">
        Reach out to your account team or contact support from your [OpenCX dashboard](https://platform.open.cx). Provide the verification data. The team submits your request.
      </Step>

      <Step title="Wait For Review">
        Verification is typically reviewed within **3 business days**. Your number may have reduced sending limits while pending.
      </Step>

      <Step title="Enable SMS">
        Once verified, go to **[Channels → SMS](https://platform.open.cx/channels/sms)**, select your toll-free number, and enable the channel.
      </Step>
    </Steps>

    <Warning>
      Unverified toll-free numbers are **blocked** from sending. Numbers pending review have reduced daily limits.
    </Warning>
  </Tab>
</Tabs>

## What Happens Without Registration?

| Scenario | Result |
| - | - |
| **US local number, no 10DLC** | Outbound texts are **silently blocked** by carriers. Inbound texts still arrive. |
| **US toll-free, no verification** | Outbound texts are **blocked**. Numbers pending review have reduced sending limits. |
| **Non-US numbers** | 10DLC does not apply. Check your country's regulations under **[Channels → SMS](https://platform.open.cx/channels/sms)**. |

***

## Related Documentation

<CardGroup>
  <Card title="Connect SMS" icon="plug" href="/sms/connect-sms">
    Go live after registration is approved.
  </Card>

  <Card title="SMS Flow" icon="route" href="/sms/message-routing">
    Session matching, delivery path, and outbound format.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/sms/troubleshooting">
    Carrier still blocking? Diagnose delivery failures.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    AI to human escalation — applies to SMS sessions.
  </Card>
</CardGroup>


# Connect SMS
Source: https://docs.open.cx/sms/connect-sms

Go live with AI SMS — verify a phone number, enable the SMS channel, handle 10DLC registration for US numbers, and confirm your first AI reply over text.

Run AI-powered SMS on a verified number. You configure it entirely from your [OpenCX dashboard](https://platform.open.cx).

## Prerequisites

* A **verified phone number** under **[Settings → Phone Numbers](https://platform.open.cx/settings/phone-numbers)**. The number must be verified before it can be used. The same number can handle voice and SMS. Turning on SMS does not change how voice calls route.

<Warning>
  US local numbers (non-toll-free +1) require **10DLC registration** before outbound texts can be delivered. Unregistered numbers are **blocked by carriers**. Have your **EIN** (or Canadian Business Number), **legal business name**, **business address**, and **contact email** ready. See [US Number Compliance](/sms/compliance) for full requirements.
</Warning>

## What You Will Configure

1. **Verified number** — purchase or import a number with SMS capability and verify it under **Settings → Phone Numbers**.
2. **SMS channel** — select that number and enable SMS under **Channels → SMS**.
3. **Test** — text the number from a real phone and confirm the AI replies.

## Go Live

<Steps>
  <Step title="Verify A Number">
    Go to **[Settings → Phone Numbers](https://platform.open.cx/settings/phone-numbers)**. Purchase a new number or verify an existing one. The number must reach **Verified** status before it can be used for SMS.
  </Step>

  <Step title="Enable The SMS Channel">
    Go to **[Channels → SMS](https://platform.open.cx/channels/sms)**. Select the verified number from the dropdown, toggle **Enable SMS Channel** on, and click **Save Settings**.
  </Step>

  <Step title="Send A Test Text">
    Text your number from a real phone. The message should appear in the dashboard inbox. If <Tooltip href="https://platform.open.cx/settings/autopilot">**Autopilot**</Tooltip> is enabled for the SMS channel, the AI will reply as plain text.
  </Step>
</Steps>

<Info>
  No AI reply? Check that **[Autopilot](https://platform.open.cx/settings/autopilot)** is enabled for SMS under your org's autopilot settings. If the number is a US local number, confirm 10DLC registration is complete.
</Info>

## Timing And Limits

Includes delivery speed, AI processing time, and <Tooltip>session auto-resolution</Tooltip>.

| Item | Detail |
| - | - |
| Inbound delivery | Incoming texts are delivered **near-instant** from the carrier. |
| AI reply | Typically **seconds** after inbound, depending on complexity. |
| Session auto-resolution | Inactive SMS sessions close after approximately **3 hours** by default. |

<Note>
  Carriers may delay or filter messages—especially for unregistered US 10DLC numbers. The dashboard shows a warning when a US local number is selected without registration.
</Note>

## Related Documentation

<CardGroup>
  <Card title="Troubleshooting" icon="wrench" href="/sms/troubleshooting">
    Missing replies, delivery failures, and common fixes.
  </Card>

  <Card title="SMS Flow" icon="route" href="/sms/message-routing">
    Session matching, delivery path, and outbound format.
  </Card>

  <Card title="US Number Compliance" icon="flag" href="/sms/compliance">
    10DLC and toll-free registration for US numbers.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    AI to human escalation — applies to SMS sessions.
  </Card>
</CardGroup>


# Sms overview
Source: https://docs.open.cx/sms/introduction

Overview of the AI SMS channel — receive texts on a verified number, reply with Autopilot, escalate to human agents, and integrate with Zendesk, HubSpot, and more.

Customers text the **number** you register in your [OpenCX dashboard](https://platform.open.cx). The **SMS channel** receives every message. When <Tooltip href="https://platform.open.cx/settings/autopilot">**Autopilot**</Tooltip> is on, AI can reply. Your team sees all conversations in the shared [inbox](https://platform.open.cx/inbox).

<Tip>
  New here? Skim this page, then open **[Connect SMS](/sms/connect-sms)** to go live.
</Tip>

## Core Functionality

<AccordionGroup>
  <Accordion title="Inbound Messages" icon="message-arrow-down">
    Customer texts arrive instantly. OpenCX matches them to existing contacts or creates new ones automatically — no manual setup per sender.
  </Accordion>

  <Accordion title="AI Responses" icon="robot">
    Your AI replies with plain text messages using the knowledge and tools you've configured. **Autopilot** controls which conversations get auto-replied.
  </Accordion>

  <Accordion title="Session Continuity" icon="link">
    Conversations stay threaded by phone number — a returning customer picks up where they left off. No extra setup needed.
  </Accordion>

  <Accordion title="Third-Party Integrations" icon="plug">
    Connect to Zendesk, HubSpot, Front, and others from the [integrations settings](https://platform.open.cx/settings/integrations).
  </Accordion>

  <Accordion title="Escalation" icon="user-group">
    When a customer needs a human, the conversation <Tooltip href="/handoff/introduction">escalates automatically</Tooltip>. Your agents reply from the inbox and the customer gets it as a text.
  </Accordion>

  <Accordion title="Shared Numbers" icon="phone">
    One number can handle both voice and SMS — enabling one doesn't affect the other.
  </Accordion>
</AccordionGroup>

<Note>
  Numbers must be verified in your [OpenCX dashboard](https://platform.open.cx/settings/phone-numbers) before they can be used.
</Note>

## Integration Options

<Tabs>
  <Tab title="SMS setup">
    Register a verified number, enable the SMS channel, and send a test text.

    <Card title="Connect SMS" icon="arrow-right" href="/sms/connect-sms">
      Number verification, channel enable, first-message test.
    </Card>
  </Tab>

  <Tab title="Third-party integrations">
    Connect helpdesks and CRMs from your [OpenCX dashboard](https://platform.open.cx/settings/integrations).

    <AccordionGroup>
      <Accordion title="Zendesk" icon="headset">
        SMS conversations sync with [Zendesk](/integrations/zendesk/sunshine-conversations). When the AI hands off, your agents pick up the conversation in their Zendesk inbox. Your agents stay in Zendesk.

        <Note>OpenCX also integrates with [Zendesk Tickets](/integrations/zendesk/ticketing-api).</Note>
      </Accordion>

      <Accordion title="Front" icon="inbox">
        SMS threads appear in your Front inbox. Handoffs route directly to your Front team with the full AI conversation attached.
      </Accordion>

      <Accordion title="Dynamics 365" icon="building">
        SMS conversations hand off into [Dynamics 365](/integrations/dynamics-365/overview) as cases. Your agents pick up in their existing Dynamics workspace.
      </Accordion>

      <Accordion title="Other integrations" icon="grid-2">
        OpenCX also supports [**HubSpot**](/integrations/hubspot/overview), [**Intercom**](/integrations/intercom/overview), [**Gorgias**](/integrations/gorgias/overview), [**Freshchat**](/integrations/freshchat/overview), and [**Twilio Flex**](/integrations/twilio-flex/overview). See [All Integrations](/dashboard/introduction) for the current list.
      </Accordion>
    </AccordionGroup>

    <CardGroup>
      <Card title="Zendesk Integration" icon="headset" href="/integrations/zendesk/overview">
        Ticketing setup and handoff.
      </Card>

      <Card title="CRM Integrations" icon="users-viewfinder" href="/crms/introduction">
        HubSpot, Salesforce, and more.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

***

## Related Documentation

<CardGroup>
  <Card title="Connect SMS" icon="plug" href="/sms/connect-sms">
    Number verification, channel enable, test message.
  </Card>

  <Card title="SMS Flow" icon="route" href="/sms/message-routing">
    Session matching, delivery path, and outbound format.
  </Card>

  <Card title="US Number Compliance" icon="flag" href="/sms/compliance">
    10DLC and toll-free registration for US numbers.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/sms/troubleshooting">
    Missing replies, delivery failures, and common fixes.
  </Card>
</CardGroup>


# SMS Flow
Source: https://docs.open.cx/sms/message-routing

How inbound texts are matched to sessions — delivery path, session continuity by phone number, and outbound plain-text format.

Use **[Connect SMS](/sms/connect-sms)** first if you have not enabled SMS on a number yet. For diagnosing issues, see **[Troubleshooting](/sms/troubleshooting)**. For US registration requirements, see **[US Number Compliance](/sms/compliance)**.

<Tip>
  **SMS Flow** covers how **OpenCX** processes texts after go-live. Setup steps stay on [Connect SMS](/sms/connect-sms).
</Tip>

## Path Of A Message

```mermaid theme={"dark"}
flowchart LR
  A([Customer]) --> B[Carrier]
  B --> C[Received]
  C --> D[Match number]
  D --> E[Session]
  E --> F[AI reply]
  F --> G([Customer])

  style A fill:#1a5c20,color:#fff,stroke:#267a2e
  style G fill:#1a5c20,color:#fff,stroke:#267a2e
```

<Steps>
  <Step title="Customer Texts Your Number">
    The customer sends an SMS to the number you registered in your [OpenCX dashboard](https://platform.open.cx/channels/sms).
  </Step>

  <Step title="Message Delivered To OpenCX">
    The message is delivered to **OpenCX** and validated.
  </Step>

  <Step title="Match Number To Org">
    **OpenCX** matches the receiving number to your org.
  </Step>

  <Step title="Find Or Create Session">
    The sender's phone number is matched against existing contacts. If a contact has an **open SMS session**, the message continues it. If the contact exists but has no open session, a new session is created. If no contact record exists, a new session and contact are created automatically.
  </Step>

  <Step title="AI Generates Reply">
    If <Tooltip href="https://platform.open.cx/settings/autopilot">**Autopilot**</Tooltip> is enabled for SMS, the AI generates a reply using your configured knowledge and tools. The reply is sent as plain text. When Autopilot is off or the session is handed off, no AI reply is generated — human agents reply from the [inbox](https://platform.open.cx/inbox) instead.
  </Step>
</Steps>

<Note>
  The thread in your [OpenCX dashboard](https://platform.open.cx) is the authoritative record. SMS has no subject-line tokens or threading headers — continuity is by **phone number** and **open session status**.
</Note>

## Outbound Format

All outbound SMS replies are **plain text**. Before sending, **OpenCX** strips HTML tags and code blocks. The cleaned message is sent through the SMS provider.

***

## Related Documentation

<CardGroup>
  <Card title="Troubleshooting" icon="wrench" href="/sms/troubleshooting">
    Missing replies, delivery failures, and common fixes.
  </Card>

  <Card title="US Number Compliance" icon="flag" href="/sms/compliance">
    10DLC and toll-free registration for US numbers.
  </Card>

  <Card title="AI Actions" icon="bolt" href="/actions/introduction">
    Run tools and workflows from SMS conversations.
  </Card>

  <Card title="Autopilot And Topics" icon="sliders" href="/handoff/topics">
    Channel-level Autopilot and topic rules.
  </Card>
</CardGroup>


# Sms troubleshooting
Source: https://docs.open.cx/sms/troubleshooting

Fix common SMS channel issues — missing replies, undelivered texts, number verification errors, and carrier blocking.

Before debugging, have these ready: your **phone number**, the **channel status** in your [OpenCX dashboard](https://platform.open.cx), and a **recent message** if available.

<Tip>
  Looking for setup steps? See [Connect SMS](/sms/connect-sms). For routing logic, see [SMS Flow](/sms/message-routing). For US number registration, see [US Number Compliance](/sms/compliance).
</Tip>

## Common Troubleshooting Scenarios

| Symptom | Likely cause | What to do |
| - | - | - |
| **No AI reply** | **Autopilot** disabled for SMS | Enable under your org's [Autopilot settings](https://platform.open.cx/settings/autopilot). |
| **Message not in inbox** | SMS delivery not configured correctly | Re-enable SMS on the number under **[Channels → SMS](https://platform.open.cx/channels/sms)** and save. |
| **"Phone number not found or not verified"** | Number not in verified-numbers list | Verify the number under **[Settings → Phone Numbers](https://platform.open.cx/settings/phone-numbers)** first. |
| **Outbound texts blocked by carrier** | Missing **10DLC registration** (US local numbers) | Complete 10DLC brand and campaign registration. See [US Number Compliance](/sms/compliance). |
| **Reply contains raw HTML** | Unusual AI output | This should not happen — contact support. |

<Info>
  If texts are not arriving in your [OpenCX dashboard](https://platform.open.cx), the problem is almost always the **number configuration** — not a platform outage.
</Info>

## Limits

| Area | Detail |
| - | - |
| **Inbound delivery** | **Near-instant** once the carrier delivers. |
| **AI processing** | Typically **seconds** — depends on complexity and knowledge lookups. |
| **Session auto-resolution** | Approximately **3 hours** of inactivity (org-level overrides possible). |
| **Concurrent AI replies** | One reply processed per session at a time. |

***

## Related Documentation

<CardGroup>
  <Card title="Connect SMS" icon="plug" href="/sms/connect-sms">
    Re-check number verification and channel setup.
  </Card>

  <Card title="SMS Flow" icon="route" href="/sms/message-routing">
    Re-check session matching and delivery path.
  </Card>

  <Card title="US Number Compliance" icon="flag" href="/sms/compliance">
    Carrier blocking? Check 10DLC and toll-free registration.
  </Card>

  <Card title="Autopilot And Topics" icon="sliders" href="/handoff/topics">
    Verify channel-level Autopilot and topic rules.
  </Card>
</CardGroup>


# 2026 08 24 voice knowledge search
Source: https://docs.open.cx/superpowers/plans/2026-08-24-voice-knowledge-search



# Voice Knowledge Search Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Give network-isolated voice agents search-first access to independently allowlisted instructions and knowledge, expose both scopes in the dashboard, and certify end-to-end behavior with production-grounded evals.

**Architecture:** The backend resolves and enforces both allowlists, embeds each query once, searches instruction mirrors and knowledge chunks concurrently, and returns one ranked top-k result through the internal voice HTTP contract. The worker only shapes the `search_knowledge` tool and forwards calls. The dashboard stores explicit instruction and knowledge selections while empty selections mean `all` independently.

**Tech Stack:** TypeScript, Fastify, Zod/OpenAPI, Kysely/PostgreSQL/pgvector, LiveKit Agents, React/TanStack Router, Vitest, OpenCX agent-eval harness.

**Spec:** `docs/superpowers/specs/2026-08-24-voice-knowledge-search-design.md`

## Global Constraints

* The voice worker imports no backend modules and reaches platform state only through `/internal/voice/v1`.
* No instruction or knowledge content is preloaded; empty selection means `all` independently for each category.
* Selected scopes fail closed and never fall back to unrestricted organization content.
* Every search enforces organization, public visibility, phone channel, contact segment, draft/deletion, and active-time boundaries before candidate limiting.
* Retrieval uses one embedding with no query-generation model or reranker.
* Every Kysely migration `up()` and `down()` begins with `SET LOCAL lock_timeout = '10s'`.
* Handwritten code remains strictly typed: no `any`, no `unknown` in MCP code, and no inline casts other than `as const`.
* Any change under `backend/voice-agent` or `backend/src/voice-runtime` requires `cd backend && pnpm voice:test` before completion.
* Public copy describes outcomes and never names internal models, providers, infrastructure vendors, or libraries.

***

### Task 1: Persist explicit knowledge selections

**Files:**

* Create: `backend/src/db/kysely-migrations/20260824160000_add_phone_agent_knowledge_scopes.ts`
* Create: `backend/src/phone/phone.knowledge-scope-persistence.spec.ts`
* Modify (generated): `backend/src/db/opencx.ts`

**Interfaces:**

* Produces `phone_agent_knowledgebase_items(id, phone_agent_id, knowledgebase_item_id)`.

* Produces `phone_agent_knowledgebase_folders(id, phone_agent_id, folder_key)`.

* Agent/item foreign keys cascade and both agent-selection pairs are unique.

* [ ] **Step 1: Write the failing schema contract test**

```ts theme={"dark"}
test('stores independent knowledge item and folder selections', async () => {
  await db.insertInto('phone_agent_knowledgebase_items').values({
    phone_agent_id: agentId,
    knowledgebase_item_id: itemId,
  }).execute();
  await db.insertInto('phone_agent_knowledgebase_folders').values({
    phone_agent_id: agentId,
    folder_key: 'website:help.example.com',
  }).execute();
  expect(await db.selectFrom('phone_agent_knowledgebase_items').selectAll().execute()).toHaveLength(1);
  expect(await db.selectFrom('phone_agent_knowledgebase_folders').selectAll().execute()).toHaveLength(1);
});
```

* [ ] **Step 2: Run RED**

Run: `cd backend && pnpm vitest run src/phone/phone.knowledge-scope-persistence.spec.ts`

Expected: type/schema failure because both tables are absent.

* [ ] **Step 3: Add the migration and regenerate types**

Implement `up()`/`down()` with lock timeout, UUID keys, cascading FKs, and unique constraints. Run `cd backend && NODE_ENV=test pnpm dev:prepare`.

* [ ] **Step 4: Run GREEN and commit**

Run: `cd backend && pnpm vitest run src/phone/phone.knowledge-scope-persistence.spec.ts`

Commit: `feat(backend, voice): persist knowledge scopes` with only the migration, generated DB type, and focused test staged.

### Task 2: Canonicalize knowledge-folder identities

**Files:**

* Create: `backend/src/rag/knowledgebase/knowledgebase-folder.utils.ts`
* Create: `backend/src/rag/knowledgebase/knowledgebase-folder.utils.spec.ts`
* Modify: `backend/src/airbyte/knowledgebase-items.service.ts`
* Modify: `backend/src/airbyte/knowledgebase-items.service.spec.ts`

**Interfaces:**

* Produces `KnowledgebaseFolderIdentity = { dataSource: KnowledgebaseDataSourceEnum; stream: string | null }`.

* Produces static `KnowledgebaseFolderUtils.toKey`, `fromKey`, and `fromItem` methods.

* [ ] **Step 1: Write table-driven RED tests with literal expectations**

```ts theme={"dark"}
it.each([
  [{ sourceType: 'website', sourceUrl: 'https://help.example.com/a' }, 'website:help.example.com'],
  [{ sourceType: 'workflow', folder: 'Returns' }, 'workflow:Returns'],
  [{ sourceType: 'workflow', folder: null }, 'workflow:'],
])('round-trips %#', (item, expectedKey) => {
  const identity = KnowledgebaseFolderUtils.fromItem(item);
  expect(KnowledgebaseFolderUtils.toKey(identity)).toBe(expectedKey);
  expect(KnowledgebaseFolderUtils.fromKey(expectedKey)).toEqual(identity);
});
```

Run: `cd backend && pnpm vitest run src/rag/knowledgebase/knowledgebase-folder.utils.spec.ts`

Expected: missing module/export.

* [ ] **Step 2: Implement and reuse the static utility**

Use URL encoding for stream delimiters, return `null` for malformed keys, and replace the browser service's duplicate website/workflow/integration classification.

* [ ] **Step 3: Run GREEN and commit**

Run: `cd backend && pnpm vitest run src/rag/knowledgebase/knowledgebase-folder.utils.spec.ts src/airbyte/knowledgebase-items.service.spec.ts src/airbyte/knowledgebase-items.workflow-folders.spec.ts`

Commit: `refactor(backend, knowledge): share folder identity`.

### Task 3: Extend phone-agent scope configuration APIs

**Files:**

* Modify: `backend/src/phone/dto/knowledge-sources.dto.ts`
* Modify: `backend/src/phone/phone.service.ts`
* Create: `backend/src/phone/phone.knowledge-scope-selection.spec.ts`
* Modify: `backend/src/phone/phone.controller.ts`
* Modify: `backend/src/public-api/controllers/phone.public.controller.ts`
* Modify: `backend/src/public-api/controllers/phone.public.controller.spec.ts`
* Modify (generated): `backend/tmp/public-openapi.json`
* Modify (generated): `backend/mcp-server/src/schema.ts`
* Modify: `backend/mcp-server/src/tools/phone.ts`
* Modify: `backend/mcp-server/src/tools/phone.spec.ts`

**Interfaces:**

* Extends update input with optional `knowledgeItemIds`/`knowledgeFolderKeys`; omission leaves knowledge rows unchanged for older clients.

* Adds instruction and knowledge modes plus explicit IDs/folder summaries to `KnowledgeSourceTreeDto` while retaining existing instruction fields.

* Adds paginated knowledge-item listing by canonical folder key.

* Changes `PhoneService.updateAgentKnowledgeSources` to one object input and one transaction.

* [ ] **Step 1: Write RED service/controller tests**

Use a literal four-row matrix for `all/all`, `selected/all`, `all/selected`, and `selected/selected`. Also assert foreign item/folder selection is rejected and a legacy two-array request does not clear knowledge rows.

Run: `cd backend && pnpm vitest run src/phone/phone.knowledge-scope-selection.spec.ts src/public-api/controllers/phone.public.controller.spec.ts`

Expected: new fields/modes and signature are absent.

* [ ] **Step 2: Implement transactional DTO/service/controller behavior**

Validate agent, directory, instruction, item, and folder ownership before writes. Lazy item listing returns IDs/titles only and filters public, non-deleted, voice-eligible rows.

* [ ] **Step 3: Run GREEN**

Run: `cd backend && pnpm vitest run src/phone/phone.knowledge-scope-selection.spec.ts src/phone/phone.knowledge-sources.nested-directories.spec.ts src/public-api/controllers/phone.public.controller.spec.ts`

* [ ] **Step 4: Regenerate public types and update MCP**

Run `cd backend && pnpm gen:spec`, then `cd mcp-server && pnpm gen:types:offline`. Extend the MCP tool with optional `knowledge_item_ids`/`knowledge_folder_keys`, forwarding only supplied arrays. Run `cd backend && pnpm --filter @opencx/mcp build && pnpm --filter @opencx/mcp test`.

* [ ] **Step 5: Commit**

Commit: `feat(backend, voice): configure search scopes` with source, generated schemas, and tests staged explicitly.

### Task 4: Replace bootstrap preloading with scope snapshots

**Files:**

* Modify: `backend/src/voice-channel/voice-agent-routing.service.ts`
* Modify: `backend/src/voice-channel/voice-agent-routing.service.spec.ts`
* Modify: `backend/src/voice-runtime/dtos/bootstrap.dto.ts`
* Modify: `backend/src/voice-runtime/dtos/events.dto.ts`
* Modify: `backend/src/voice-channel/voice-call-session.service.ts`
* Modify: `backend/src/chat-session/dtos/chat-session.dto.ts`
* Modify: `backend/src/voice-runtime/services/voice-bootstrap.service.ts`
* Modify: `backend/src/voice-runtime/__tests__/voice-bootstrap.e2e.spec.ts`

**Interfaces:**

* Produces `VoiceAgentRoutingService.getKnowledgeScope({ agentId, contactId })`.

* Snapshot: `{ instruction_scope: { mode, instruction_ids, directory_ids }, knowledge_scope: { mode, item_ids, folder_keys }, captured_at }`.

* Bootstrap excludes selected content while explicit dynamic instructions remain appended.

* [ ] **Step 1: Write RED routing/bootstrap tests**

```ts theme={"dark"}
expect(response.instructions).not.toContain(INSTRUCTION_SENTINEL);
expect(response.knowledge.snapshot?.instruction_scope).toEqual({
  mode: 'selected', instruction_ids: [instructionId], directory_ids: [],
});
expect(response.knowledge.snapshot?.knowledge_scope.mode).toBe('all');
```

Add knowledge-selected/instructions-all and dynamic-instruction cases. Run `cd backend && pnpm vitest run src/voice-channel/voice-agent-routing.service.spec.ts src/voice-runtime/__tests__/voice-bootstrap.e2e.spec.ts`.

Expected: selected content is still preloaded and new fields are missing.

* [ ] **Step 2: Implement no-preload scope resolution**

Determine mode from raw explicit rows, keep explicit directory/folder selectors for audit, and resolve contact-eligible selected instruction/item IDs separately. Preserve dynamic instruction assembly.

* [ ] **Step 3: Run GREEN and commit**

Run: `cd backend && pnpm vitest run src/voice-channel/voice-agent-routing.service.spec.ts src/voice-runtime/__tests__/voice-bootstrap.e2e.spec.ts`

Commit: `feat(backend, voice): bootstrap search scopes`.

### Task 5: Build scoped, ranked backend retrieval

**Files:**

* Modify: `backend/src/rag/knowledgebase/knowledgebase.ts`
* Create: `backend/src/rag/knowledgebase/knowledgebase.allowlist.spec.ts`
* Create: `backend/src/voice-runtime/services/voice-knowledge-search.service.ts`
* Create: `backend/src/voice-runtime/services/voice-knowledge-search.service.spec.ts`

**Interfaces:**

* Extends `KnowledgebaseService.search` with strict `sourceRecordIds`, `allowedItemIds`, and `allowedFolderKeys`; `undefined` is unrestricted and `[]` returns no results.

* Produces `VoiceKnowledgeSearchService.search({ orgId, agentId, contactId, query })`.

* Results are `{ type, id, chunkIndex, title, content, sourceUrl }`, ranked together by distance and capped at five.

* [ ] **Step 1: Write RED access-filter tests**

Seed a closer forbidden vector and farther allowed vector, then assert the allowed one survives `limit: 1`. Cover empty scope, segment member/non-member, draft, deleted, scheduled, private, wrong-channel, and foreign rows with literal IDs.

Run: `cd backend && pnpm vitest run src/rag/knowledgebase/knowledgebase.allowlist.spec.ts`

Expected: new search parameters are absent or the forbidden row wins.

* [ ] **Step 2: Implement SQL predicates before ANN limiting**

Apply filters to embedding and include-by-ID queries; immediately return `[]` for explicitly empty scopes. Run the allowlist test plus existing segment/channel/schedule/deletion specs.

* [ ] **Step 3: Write RED service tests**

Use real DB vectors and mock only the external embedding response with its complete shape. Test independent scopes, authoritative instruction status filtering, distance merge across result types, truncation, no match, and telemetry-safe IDs.

Run: `cd backend && pnpm vitest run src/voice-runtime/services/voice-knowledge-search.service.spec.ts`

Expected: module missing.

* [ ] **Step 4: Implement one-embedding concurrent retrieval**

Query instruction mirrors and normal knowledge concurrently; re-read matched instruction rows with `TrainingService.getAiInstructionsByIds`, merge comparable distances, cap to five, and never put content in span attributes.

* [ ] **Step 5: Run GREEN and commit**

Run: `cd backend && pnpm vitest run src/voice-runtime/services/voice-knowledge-search.service.spec.ts src/rag/knowledgebase/knowledgebase.allowlist.spec.ts src/rag/knowledgebase/knowledgebase.segments.spec.ts src/rag/knowledgebase/knowledgebase.channel-schedule.spec.ts src/rag/knowledgebase/knowledgebase.soft-deleted-excluded.spec.ts`

Commit: `feat(backend, voice): search scoped knowledge`.

### Task 6: Expose the internal voice search endpoint

**Files:**

* Create: `backend/src/voice-runtime/dtos/knowledge-search.dto.ts`
* Modify: `backend/src/voice-runtime/voice-call-ops.controller.ts`
* Create: `backend/src/voice-runtime/__tests__/voice-knowledge-search.e2e.spec.ts`
* Modify: `backend/src/voice-runtime/contract-version.ts`
* Modify: `backend/voice-agent/src/__tests__/deploy-workflow.guard.spec.ts`
* Modify: `.github/workflows/voice-agent-deploy.yml`

**Interfaces:**

* Adds `voiceSearchKnowledge` at `POST /internal/voice/v1/sessions/{sessionId}/tools/knowledge-search`.

* Request: `{ orgId, agentId, query }`, trimmed to 1–500 characters.

* Response status: `ok | no_match | restricted_empty`, plus both modes and typed results.

* [ ] **Step 1: Write RED real-HTTP tests**

Assert exact seeded IDs for a valid session, 404 for foreign org/agent/session, 400 for blank query, and a bounded backend deadline.

Run: `cd backend && pnpm vitest run src/voice-runtime/__tests__/voice-knowledge-search.e2e.spec.ts`

Expected: route 404.

* [ ] **Step 2: Implement guarded route and deadline**

Use `requireSession` and `requireAgent`, require the session's phone agent to equal `agentId`, and pass the session contact ID to search.

* [ ] **Step 3: Bump/pin contract and run GREEN**

Use one new version literal in backend, deploy guard, and both deploy readiness checks. Run runtime/contract/deploy-guard tests.

* [ ] **Step 4: Commit**

Commit: `feat(backend, voice): expose knowledge search`.

### Task 7: Register the isolated worker search tool

**Files:**

* Modify (generated): `backend/tmp/voice-openapi.json`
* Modify (generated): `backend/voice-agent/src/api/schema.ts`
* Modify: `backend/voice-agent/src/api/voice-backend-api.ts`
* Modify: `backend/voice-agent/src/api/voice-backend-api.spec.ts`
* Create: `backend/voice-agent/src/tools/knowledge.tools.ts`
* Create: `backend/voice-agent/src/tools/knowledge.tools.spec.ts`
* Modify: `backend/voice-agent/src/voice-agent-dynamic-imports.ts`
* Modify: `backend/voice-agent/src/voice-agent-dynamic-imports.spec.ts`
* Modify: `backend/voice-agent/src/index.ts`
* Modify: `backend/voice-agent/src/testing.ts`

**Interfaces:**

* Produces `VoiceBackendApi.searchKnowledge` with a four-second client deadline.

* Produces `getKnowledgeTools({ orgId, agentId, sessionId })` and `search_knowledge`.

* Tool preserves exact IDs; corpus miss and unavailability have distinct honest-answer guidance.

* [ ] **Step 1: Write RED API/tool tests**

Test success serialization, `no_match` guidance containing `do not guess`, unavailable guidance on rejected HTTP, and the exact timeout passed by the façade.

Run: `cd backend && pnpm --filter @opencx/voice-agent test src/api/voice-backend-api.spec.ts src/tools/knowledge.tools.spec.ts`

Expected: API method/tool missing.

* [ ] **Step 2: Regenerate and implement**

Dump the internal spec, run `cd backend/voice-agent && pnpm gen:client:offline`, implement the API/tool, add a literal dynamic-import thunk to the prewarm list, and merge the tool for every resolved agent.

* [ ] **Step 3: Run GREEN, isolation, type, and build checks**

Run: `cd backend && pnpm --filter @opencx/voice-agent test && pnpm --filter @opencx/voice-agent test:isolation && pnpm --filter @opencx/voice-agent tsgo && pnpm --filter @opencx/voice-agent build`

* [ ] **Step 4: Commit**

Commit: `feat(voice-agent): add knowledge search tool`.

### Task 8: Build the two-folder dashboard selector

**Files:**

* Modify: `dashboard/apps/dashboard/app/(authenticated)/(dashboard)/(channels)/channels/phone/_components/KnowledgeSourcesSelector/selection.utils.ts`
* Modify: `dashboard/apps/dashboard/app/(authenticated)/(dashboard)/(channels)/channels/phone/_components/KnowledgeSourcesSelector/selection.utils.test.ts`
* Modify: `dashboard/apps/dashboard/app/(authenticated)/(dashboard)/(channels)/channels/phone/_components/KnowledgeSourcesSelector/index.tsx`
* Create: `dashboard/apps/dashboard/app/(authenticated)/(dashboard)/(channels)/channels/phone/_components/KnowledgeSourcesSelector/index.test.tsx`
* Modify: `dashboard/apps/dashboard/app/(authenticated)/(dashboard)/(channels)/channels/phone/_components/ModifyAIPhoneAgent/ModifyAIPhoneAgent__Form.tsx`
* Modify (generated): `dashboard/packages/sdk/src/schema.ts`

**Interfaces:**

* Selection utilities track instruction IDs/directories separately from knowledge item IDs/folder keys.

* Component ref remains `save`, `hasChanges`, `fetchTree`.

* Roots expose `All searchable` or `Restricted · N selected` as visible text.

* [ ] **Step 1: Write RED utility tests**

Assert zero means all, first checked child restricts only its category, instruction changes do not dirty knowledge, inherited rows stay implicit, and clearing the final selection restores all.

Run: `cd dashboard && pnpm --filter @open/dashboard test -- KnowledgeSourcesSelector/selection.utils.test.ts`

Expected: knowledge selection API absent.

* [ ] **Step 2: Implement pure state utilities and run GREEN**

Keep set arithmetic outside React. Rerun the focused utility test.

* [ ] **Step 3: Write RED component tests**

Render the real component with API handlers. Assert named keyboard-operable root disclosures, both statuses, lazy folder item loading, independent status change, and retained local checks after a save failure.

Run: `cd dashboard && pnpm --filter @open/dashboard test -- KnowledgeSourcesSelector/index.test.tsx`

Expected: roots/lazy UI absent.

* [ ] **Step 4: Regenerate SDK and implement the component**

Run `pnpm gensdk`. Replace token warnings with scope summaries; use native checkboxes, existing Collapsible primitives, visible focus, text states, and folder-level lazy pagination.

* [ ] **Step 5: Run GREEN, typecheck, lint, and commit**

Run focused selector tests, `cd dashboard && pnpm --filter @open/dashboard type-check`, and focused lint. Commit: `feat(dashboard, voice): configure search scopes`.

### Task 9: Port and expand production-grounded evals

**Files:**

* Create: `backend/src/agent-evals/benches/foodics-voice-knowledge.bench.spec.ts`
* Modify: `backend/src/agent-evals/benches/foodics-voice.bench.spec.ts`
* Modify: `backend/src/agent-evals/gate-runner-config.ts`
* Modify: `backend/src/agent-evals/gate-runner-config.spec.ts`
* Create: `backend/src/agent-evals/research/foodics-voice-knowledge-search.md`
* Modify: `backend/src/voice-e2e/provider-roundtrip.e2e.spec.ts`
* Modify: `backend/scripts/voice-smoke/provider-roundtrip-helpers.ts`

**Interfaces:**

* `FoodicsKnowledgeCall.start` uses `RealBackendTestServer`, `VoiceBackendApi.bootstrap`, and `getKnowledgeTools`.

* Artifacts include scope snapshot, tool input/output, exact IDs, latency, and priced usage.

* Both voice gate targets include `moneygram-voice` and `foodics-voice-knowledge`.

* [ ] **Step 1: Write/run RED gate-config test**

Expect both target bench arrays to equal `['moneygram-voice', 'foodics-voice-knowledge']`. Run the focused config spec and observe failure.

* [ ] **Step 2: Port production-grounded cases at K=1**

Port Foodics Waiter code, KDS near-duplicate, Arabic-to-English cashier PIN, and drone-delivery corpus miss through real HTTP bootstrap/search. Assert exact retrieval IDs before judging the spoken answer.

* [ ] **Step 3: Add K=1 gap cases**

Add multi-turn follow-up, selected instructions plus all knowledge, selected knowledge plus all instructions, segment member/non-member no-leak pair, and stable synthetic conflict/staleness when production data lacks the edge.

* [ ] **Step 4: Add deterministic no-preload and latency contracts**

Against the restored 3,143-item corpus, assert zero bootstrap preload and each repeated search completes under three seconds with expected IDs.

* [ ] **Step 5: Run K=1 and repair only evidence-backed failures**

Run `cd backend && AGENT_EVALS=1 EVAL_K=1 pnpm vitest run src/agent-evals/benches/foodics-voice-knowledge.bench.spec.ts` and require an artifact per test.

* [ ] **Step 6: Add opt-in audio knowledge roundtrip**

Reuse participant-audio publication and provider attribution; assert user transcript, search tool evidence, grounded assistant row, and post-turn audio under existing provider prerequisites.

* [ ] **Step 7: Run both voice targets at K=10 and commit**

Run the gate runner for both target models, record cost/latency, and classify failures from IDs/traces. Commit: `test(backend, voice): gate knowledge search`.

### Task 10: Verify, review, repair, and open the draft PR

**Files:**

* Review every file changed from base `5f10cfcf674eca5e771be8b6c2663397e938cdc2`.
* Modify only files required by failing verification or concrete review findings.

**Interfaces:**

* Pushes `m-tabaza/feature/voice-knowledge-search-v2`.

* Opens a draft PR based on `m-tabaza/feat/voice-agent-network-isolation` until #2260 merges.

* [ ] **Step 1: Run focused verification**

Run backend `pnpm tsgo`, MCP build/tests, worker type/unit/isolation/build, dashboard type/focused tests, and every touched backend spec.

* [ ] **Step 2: Run mandatory full voice verification**

Run: `cd backend && pnpm voice:test`

Expected: PASS across worker unit/isolation and backend/runtime/worker-spawning voice suites.

* [ ] **Step 3: Run formatting/lint/diff checks**

Run `pnpm fmt:check`, `pnpm lint`, `git diff --check`, and inspect generated-file drift.

* [ ] **Step 4: Review for production readiness**

Inspect the full base diff for tenant leaks, selected-to-all fallback, wrong empty-array semantics, stale scope use, unbounded response/context, timeout mismatch, direct worker backend imports, permission gaps, public compatibility, migration lock timeout, contract drift, inaccessible UI state, and eval assertions that test mocks.

* [ ] **Step 5: Fix each concrete issue through RED/GREEN**

For every finding, first add a focused failing regression test, observe the expected failure, make the smallest fix, then rerun the affected suite/type/lint checks. Commit independent fixes atomically.

* [ ] **Step 6: Push and open the draft PR**

Push the branch, then run `gh pr create --draft --repo opencx-labs/opencx --base m-tabaza/feat/voice-agent-network-isolation --head m-tabaza/feature/voice-knowledge-search-v2 --title "feat: add voice knowledge search" --body-file /tmp/voice-knowledge-search-pr.md`.

The PR body includes independent scope semantics, no-preload behavior, network boundary, eval results, exact verification commands, stacked dependency on #2260, and remaining non-gating risks.


# 2026 08 26 luna voice search hardening
Source: https://docs.open.cx/superpowers/plans/2026-08-26-luna-voice-search-hardening



# Luna Voice Search Hardening Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Certify Luna as the only voice model and make voice instruction/knowledge retrieval speculative, multilingual, scoped, grounded, and reliable.

**Architecture:** Luna emits an array of query variants. The backend batch-embeds and interleaves strict-scope instruction and knowledge searches, while a worker coordinator observes LiveKit's preemptive LLM tool-call chunks and starts only the read-only search early. Search-first enforcement happens in the worker LLM node; workflow/output/harness fixes follow focused reproductions.

**Tech Stack:** TypeScript, Vitest, Zod, LiveKit Agents 1.5.1, OpenAI embeddings, Kysely/Postgres/pgvector.

**Spec:** `docs/superpowers/specs/2026-08-26-luna-voice-search-hardening-design.md`

## Global Constraints

* Voice evals and release gates target `gpt-5.6-luna` only; GPT-5.5 is deprecated.
* Instruction and knowledge selections are independent strict allowlists; an empty selection means all content in that category is searchable.
* Do not preload corpus content into the network-isolated worker.
* Speculative execution is read-only knowledge search only.
* Do not start, stop, or kill a shared backend or LiveKit worker.
* Do not stage, commit, push, or create/update a PR without explicit git-write permission.

***

### Task 1: Luna-only gate

**Files:**

* Modify: `.agents/skills/agent-evals/SKILL.md`
* Modify: `backend/src/agent-evals/gate-runner-config.ts`
* Test: `backend/src/agent-evals/gate-runner-config.spec.ts`
* Modify: `backend/src/agent-evals/benches/foodics-voice-knowledge.bench.spec.ts`

**Interfaces:**

* Produces: default target list `['v2', 'voice-luna']`; `voice-luna` has no deprecated comparison target.

* [ ] Change the existing gate assertion to expect only `v2` and `voice-luna`, and assert `voice-gpt-5.5` is absent.

* [ ] Run `pnpm test src/agent-evals/gate-runner-config.spec.ts`; expect the old target matrix assertion to fail.

* [ ] Remove the GPT-5.5 target and comparison, make Luna the documented production voice target, and replace confusing voice-eval snapshot metadata defaults with Luna.

* [ ] Rerun the focused spec; expect PASS.

### Task 2: Multi-query search contract

**Files:**

* Modify: `backend/src/voice-runtime/dtos/knowledge-search.dto.ts`
* Modify: `backend/src/voice-runtime/services/voice-knowledge-search.service.ts`
* Test: `backend/src/voice-runtime/services/voice-knowledge-search.service.spec.ts`
* Modify: `backend/voice-agent/src/api/schema.ts` (generated)
* Modify: `backend/voice-agent/src/api/voice-backend-api.ts` (generated-client consumer contract only if generation requires it)
* Modify: `backend/voice-agent/src/tools/knowledge.tools.ts`
* Test: `backend/voice-agent/src/tools/knowledge.tools.spec.ts`

**Interfaces:**

* Consumes: `queries: readonly [string, ...string[]]`, length 1-4, each query 1-500 characters.

* Produces: one batched embedding call and one response containing strict-scope interleaved results.

* [ ] Add DTO/tool tests proving query arrays are forwarded in order, deduplicated after normalization, and capped at four.

* [ ] Run the two focused specs; expect schema/forwarding failures.

* [ ] Change the wire DTO from `query` to `queries`; batch embeddings with `input: queries`.

* [ ] Search both categories for every non-empty embedding, round-robin interleave per-query candidates by `type:id:chunkIndex`, then feed the combined candidates to the final ranker.

* [ ] Generate the offline OpenAPI/client schema and rerun the focused specs; expect PASS.

### Task 3: Category-aware relevance and pinning

**Files:**

* Modify: `backend/src/voice-runtime/services/voice-knowledge-ranking.utils.ts`
* Test: `backend/src/voice-runtime/services/voice-knowledge-ranking.utils.spec.ts`
* Modify: `backend/src/voice-runtime/dtos/knowledge-search.dto.ts`
* Modify: `backend/src/voice-runtime/services/voice-knowledge-search.service.ts`
* Test: `backend/src/voice-runtime/services/voice-knowledge-search.service.spec.ts`

**Interfaces:**

* Consumes: multiple query profiles and optional prior result IDs split by instruction/knowledge.

* Produces: a maximum of five results, with both source categories represented when each has a relevant candidate; weak candidates produce `no_match`.

* [ ] Add ranking tests for KDS positive-only queries, bilingual query union, per-category representation, authorized prior-ID pinning, and unrelated-corpus abstention.

* [ ] Run the focused ranking/search specs; expect failures for missing multi-query scoring, pinning, and abstention.

* [ ] Score each candidate against its best query profile, keep negated terms as penalties, pin authorized prior IDs without bypassing scope/segments, and add a conservative relevance cutoff based on vector distance plus lexical evidence.

* [ ] Add telemetry for per-query candidate counts, best scores, selected IDs, and no-match reason.

* [ ] Rerun focused specs; expect PASS.

### Task 4: LiveKit preemptive read-only search

**Files:**

* Create: `backend/voice-agent/src/knowledge-search-coordinator.ts`
* Create: `backend/voice-agent/src/knowledge-search-coordinator.spec.ts`
* Modify: `backend/voice-agent/src/tools/knowledge.tools.ts`
* Modify: `backend/voice-agent/src/voice-agent.ts`
* Test: `backend/voice-agent/src/tools/knowledge.tools.spec.ts`
* Test: `backend/voice-agent/src/voice-agent.spec.ts`
* Modify: `backend/voice-agent/src/index.ts`
* Modify: `backend/src/agent-evals/voice-knowledge-eval.call.ts`
* Modify: `backend/src/agent-evals/benches/moneygram-voice.bench.spec.ts`

**Interfaces:**

* Produces: `VoiceKnowledgeSearchCoordinator.tools`, `observeLlmChunk(chunk)`, and exact-query promise reuse for `search_knowledge` only.

* [ ] Add tests where an observed `search_knowledge` `ChatChunk` starts the backend request before `tool.execute`, and execution reuses the same promise exactly once.

* [ ] Add tests proving malformed arguments, other tools, changed arguments, rejected searches, and cache eviction never trigger or reuse unsafe work.

* [ ] Run coordinator/tool tests; expect missing-coordinator failures.

* [ ] Implement a bounded per-call cache keyed by normalized validated args; no other tool name may enter it.

* [ ] Change `createAssistant` to use LiveKit's documented `Agent.create({ llmNode })`, delegate to `Agent.default.llmNode`, observe chunks without delaying/yield mutation, and preserve the original stream.

* [ ] Wire the coordinator into production and in-process voice evals; rerun focused unit tests and expect PASS.

### Task 5: Runtime search-first enforcement

**Files:**

* Create: `backend/voice-agent/src/knowledge-search-turn.utils.ts`
* Test: `backend/voice-agent/src/knowledge-search-turn.utils.spec.ts`
* Modify: `backend/voice-agent/src/voice-agent.ts`
* Test: `backend/voice-agent/src/voice-agent.spec.ts`

**Interfaces:**

* Produces: `VoiceKnowledgeSearchTurnUtils.requiresSearch(chatCtx): boolean` and exact LiveKit function tool choice for `search_knowledge` only before the latest substantive caller turn has a search result.

* [ ] Add literal chat-context tests for substantive policy questions, third-party questions, eight-to-twelve-digit references, greetings, yes/no acknowledgements, survey keypad answers, and post-search regeneration.

* [ ] Run focused tests; expect failures because tool choice remains automatic.

* [ ] Apply the exact function tool choice only on the first generation that requires search; preserve caller/model tool choice after a search result.

* [ ] Rerun focused tests; expect PASS.

### Task 6: Focused workflow state fixes

**Files:**

* Modify only the reusable worker/backend tool-orchestration files identified by each failing focused test.
* Add a colocated spec for every new function or state transition.
* Preserve hard assertions in `backend/src/agent-evals/benches/moneygram-voice.bench.spec.ts`.

**Interfaces:**

* Produces: typed workflow `nextAction`, `requiredInput`, and `attemptsRemaining` where supported; survey state owns question/answer/submission order.

* [ ] Run Luna K=1 for failed-surname, caller-type-lock, card-troubleshooting, Spanish-survey, and survey-interruption scenarios without external workers; capture fresh artifacts.

* [ ] For each reproducible failure, write one focused failing test at the tool/result boundary before changing production behavior.

* [ ] Implement the smallest reusable state transition that fixes that failure; never key production logic by customer/org ID.

* [ ] Rerun its focused unit test and scenario before moving to the next transition.

### Task 7: Spoken output and eval harness

**Files:**

* Modify: `backend/src/agent-evals/voice-latency-eval.utils.ts`
* Test: `backend/src/agent-evals/voice-latency-eval.utils.spec.ts`
* Modify the existing worker spoken-output utility selected by focused reproduction.
* Add its colocated spec.

**Interfaces:**

* Produces: terminal/tool-only latency classification and deterministic spoken formatting for telephone/reference numbers and uppercase initialisms.

* [ ] Add failing tests for terminal `end_call` without a streamed sentence, phone/reference digit preservation, and initialism expansion.

* [ ] Run focused specs; expect failures.

* [ ] Classify terminal tool-only turns without manufacturing spoken latency, and normalize structured values before TTS.

* [ ] Rerun focused specs; expect PASS.

### Task 8: Review and Luna certification

**Files:**

* Review every changed file with `git diff --check` and `git diff`.
* Update: `backend/src/agent-evals/research/foodics-voice-knowledge-search.md`
* Update: `backend/src/agent-evals/research/moneygram-voice.md`
* Update: `backend/src/agent-evals/research/ticketswap-voice-knowledge-search.md`

**Interfaces:**

* Produces: Luna-only GO/NO-GO report with 100% hard-scenario requirement.

* [ ] Run touched unit/integration specs and `pnpm tsgo`; fix every failure.

* [ ] Run Foodics, TicketSwap, and focused MoneyGram Luna K=1 in process; do not run worker cleanup commands.

* [ ] Run the full Luna matrix at K=1; fix regressions.

* [ ] Run focused failed scenarios at K=10.

* [ ] Run `pnpx bun src/agent-evals/gate-runner.ts --targets voice-luna --k 10` and report exact pass/fail counts, latency, cost, and artifact path.


# 2026 08 24 voice knowledge search design
Source: https://docs.open.cx/superpowers/specs/2026-08-24-voice-knowledge-search-design



# Voice Knowledge Search Design

## Goal

Replace voice-agent knowledge preloading with search-first retrieval while preserving strict, independently configurable access boundaries for work instructions and knowledge-base content. The voice worker remains network-isolated: it receives scope metadata at bootstrap and performs retrieval only through the internal voice HTTP API.

## Product semantics

Instructions and knowledge are separate optional allowlists. An empty selection means search everything in that category; one or more selections restrict only that category.

| Instruction selection | Knowledge selection | Searchable corpus |
| - | - | - |
| None | None | All eligible instructions and all eligible knowledge |
| Some | None | Selected instructions and all eligible knowledge |
| None | Some | All eligible instructions and selected knowledge |
| Some | Some | Selected instructions and selected knowledge |

No instruction or knowledge content is preloaded in this version. A later optimization may replace search with preload when an allowed corpus is proven small, but that optimization must preserve the same scope semantics and eval contracts.

Per-call dynamic instructions remain a separate explicit mechanism. They continue to be appended to the call prompt when requested and do not alter either search allowlist.

## Scope model and persistence

Instruction scope reuses the existing explicit selections:

* `phone_agent_instructions` for individual instructions.
* `phone_agent_selected_directories` for an instruction directory and all current or future descendants.
* No rows in either table means `all`; any row means `selected`.

Knowledge scope gains two equivalent selection forms:

* Individual knowledge-base item selections, with foreign keys to the agent and item.
* Virtual knowledge-folder selections, using the canonical folder identity already used by the knowledge browser. A folder selection covers current and future items classified into that folder.
* No knowledge item or folder rows means `all`; any row means `selected`.

The canonical folder-key utility is shared by the knowledge browser, dashboard selector, validation, and retrieval filter so a displayed folder cannot resolve differently at search time. New selection tables use cascading foreign keys where a physical record exists, tenant-scoped validation on every write, unique constraints, and a migration with the required `lock_timeout`.

Existing agents need no data migration. Existing instruction selections become a selected instruction scope; absence of knowledge selections means all eligible knowledge is searchable. The legacy hidden `use_org_knowledgebase` control does not define the new scope.

## Bootstrap and runtime contract

Bootstrap stops assembling selected instruction content. Its prompt contains only the agent's base instructions, explicitly requested dynamic instructions, and existing per-call additions.

Bootstrap returns and persists a scope snapshot shaped around two independent categories:

* instruction mode plus explicit instruction and directory identifiers;
* knowledge mode plus explicit item and folder identifiers;
* capture timestamp.

The snapshot is for audit and eval assertions. Authorization is re-evaluated on every search so a mid-call configuration change fails closed instead of relying on stale bootstrap state.

The worker always registers `search_knowledge` for a resolved phone agent. The tool calls a typed endpoint under `/internal/voice/v1/sessions/:sessionId/tools/knowledge-search` with the organization, agent, and a short standalone query. The backend verifies service authentication, session ownership, agent ownership, and that the session belongs to the agent before resolving contact-aware scope.

This is a breaking internal wire change, so the voice runtime contract version, generated worker client, deploy preflight pins, and contract guard tests change together.

## Retrieval pipeline

The backend owns the complete retrieval path:

1. Resolve the current instruction and knowledge modes independently.
2. Expand selected instruction directories and selected knowledge folders.
3. Apply organization, public visibility, phone-channel, contact segment, draft/deletion, and active-time restrictions before candidate limiting.
4. Create one embedding for the tool query.
5. Search instruction mirrors and knowledge chunks concurrently, retaining comparable vector distances.
6. Merge and rank both result types into one precision-oriented top-k response.

Instruction matches are authoritatively joined back to published instruction rows before return; stale mirrors cannot expose draft, expired, wrong-channel, wrong-segment, or foreign instructions. Knowledge allowlist predicates are pushed into the database query before the nearest-neighbor limit so a small selected folder is not crowded out by forbidden high-scoring candidates.

Each result contains a stable type, source identifier, chunk index where applicable, title, bounded content, and optional source URL. The model does not need raw vector distances, but backend telemetry records the query, both scope modes, candidate counts, returned IDs, latency, and result status.

There is no query-generation model or reranker in the first version. The voice model receives the call history and is instructed to submit a standalone search query containing the relevant prior-turn context. Tool outputs remain in the agent session context. Results are deliberately few and content is truncated to bound both time-to-first-response and context growth.

The backend owns a deadline shorter than the worker's request deadline. A genuine miss returns `no_match`; backend or network failure returns an unavailable outcome from the worker wrapper. Both outcomes tell the agent not to invent facts and to use its existing instructions or offer the configured fallback.

## Dashboard configuration

The existing phone-agent Knowledge Sources section becomes a search-scope selector with two independently expandable root groups:

* **Instructions** — the current instruction directory tree and individual instructions.
* **Knowledge** — knowledge-source folders with lazy, paginated item loading for large corpora.

Each root displays `All searchable` when it has no selection and `Restricted` with a selected count otherwise. Selecting the first child visibly changes that category to restricted and shows concise help text explaining that only checked content will be searched. Clearing the last selection restores `All searchable`.

Folder selections include current and future descendants/items. Individual selections outside a selected folder remain explicit. The API returns explicit selections separately from effective inherited state so saving cannot accidentally make descendants permanent.

The existing preload token meter and memory-cap warnings are removed because selected content no longer enters the initial prompt. The selector uses native checkboxes, semantic group labels, keyboard-operable disclosure controls, visible focus states, and text in addition to color for `All searchable`, `Restricted`, inherited, unsaved, loading, and failure states. Knowledge items load only when their folder opens; loading and save failures remain recoverable without losing local selection state.

## Eval and test coverage

### Deterministic contracts

* All four independent scope combinations in the product-semantics table.
* Directory/folder descendant inheritance, future-item inclusion, individual selection, and clearing the final selection back to `all`.
* Cross-organization rejection on dashboard writes and runtime searches.
* Same-query contact pair proving segment-member inclusion and non-member exclusion by exact result ID.
* Draft, deleted, expired/not-yet-active, private, and wrong-channel exclusions.
* Unified top-k ordering across near-duplicate instruction and knowledge results.
* No bootstrap preloading in either scope mode.
* Search timeout, upstream failure, empty embedding, and no-match behavior.
* Worker tool serialization, typed HTTP calls, and contract-version/deploy guards.
* Dashboard selection utilities, lazy folder loading, independent dirty-state tracking, keyboard controls, and accessible names/status text.

### Voice behavior evals

Port the existing Foodics knowledge scenarios onto the production-shaped HTTP bootstrap and search boundary used by the MoneyGram voice bench. Every scenario asserts both end behavior and exact retrieval/tool evidence:

* Production-grounded English how-to retrieval.
* Near-duplicate product discrimination.
* Arabic query retrieving English source material and answering in Arabic.
* Honest handling of a corpus miss.
* Multi-turn follow-up whose second query must carry context from the first turn or correctly reuse the retained result.
* Strict instruction allowlist plus unrestricted knowledge.
* Strict knowledge allowlist plus unrestricted instructions.
* Segment-member/non-member pair with a hard no-leak assertion.
* Conflicting or stale synthetic documents where production data cannot provide a stable fixture.

Run new scenarios at K=1 while developing, then K=10 for hard assertions before certification. Retrieval IDs, tool inputs/outputs, scope snapshots, latency, and priced transcript artifacts are saved for diagnosis.

A real participant-audio knowledge scenario is added to the opt-in provider-roundtrip suite when the local voice stack is available. It proves audio to transcription to tool call to spoken answer, while the merge gate keeps the less flaky text-turn semantic scenarios that still use the real voice model and real HTTP retrieval boundary.

## Rollout and observability

The stacked PR targets the network-isolation branch until that branch merges, then retargets to `main`. Deployment requires the backend contract first and the existing readiness preflight before workers roll.

Operational telemetry distinguishes `ok`, `no_match`, `restricted_empty`, `timeout`, and `unavailable`, and records instruction/knowledge scope modes plus returned identifiers. It must never record full private document bodies in span attributes.

## Non-goals

* No automatic preload threshold in this PR.
* No query-generation model, semantic reranker, or persistent server-side conversation memory.
* No dashboard control for making a category search nothing; an empty selection intentionally means all.
* No direct database, embedding-provider, or backend module import from the voice worker.
* No silent fallback from a selected category to the organization's unrestricted corpus.


# 2026 08 26 luna voice search hardening design
Source: https://docs.open.cx/superpowers/specs/2026-08-26-luna-voice-search-hardening-design



# Luna Voice Search Hardening Design

## Goal

Make Luna the only production voice-eval target and make voice knowledge/instruction answers search-first, multilingual, grounded, and low-latency without preloading an organization's corpus into the worker.

## LiveKit research decision

LiveKit Agents 1.5.1 enables preemptive generation by default. The SDK begins the LLM request when it receives a final transcript segment before end-of-turn confirmation, but it waits for the speech handle to be scheduled and authorized before executing function tools. LiveKit documents `Agent.llmNode` as the customization point for observing LLM chunks and tool calls.

Primary documentation:

* [Preemptive generation and turn completion](https://docs.livekit.io/agents/multimodality/audio/)
* [Turn-taking tuning and preemptive limits](https://docs.livekit.io/agents/logic/turns/tuning/)
* [Pipeline node hooks, including `llmNode`](https://docs.livekit.io/agents/logic/nodes/)
* [`user_input_transcribed` interim/final events](https://docs.livekit.io/reference/agents/events/)
* [Turn-handling options](https://docs.livekit.io/reference/agents/turn-handling-options/)

The documented RAG hook, `on_user_turn_completed`, runs after the turn; it cannot hide retrieval under a long caller utterance. The exact installed SDK source also confirms that preemptive generation starts LLM inference early but defers normal function-tool execution until the speech handle is authorized. This is why the design observes completed search arguments in `llmNode` instead of speculatively executing arbitrary LiveKit tools.

LiveKit documents interim transcript events, but does not document executing
tools from unstable interim text or reconciling those effects when a transcript
is revised. The design therefore does not invent an interim-transcript tool
runner. It uses LiveKit's supported preemptive generation window: a final STT
segment can start the LLM while the caller is still speaking or while end-of-turn
confirmation is pending, and only completed read-only search arguments are
executed early.

LiveKit also documents that preemptive generation is skipped once speech exceeds
`maxSpeechDuration`, whose default is 10 seconds. Production raises that bound to
60 seconds so ordinary long support explanations can still overlap LLM and
search work with the caller's speech. Preemptive TTS remains disabled, retries
remain capped at three, and turns longer than one minute fall back to normal
post-turn generation to bound discarded model/search work.

The worker will therefore observe completed `search_knowledge` tool-call arguments in `llmNode`. During a preemptive generation it may start that read-only search immediately and cache the in-flight promise. When LiveKit later authorizes the tool after end-of-turn, the normal tool execution reuses the exact promise. Speculative transfer, workflow, action, survey-submission, and hangup tools remain prohibited because they have side effects and a preemptive generation can be discarded.

## Search contract

`search_knowledge` accepts one to four standalone queries. Luna supplies, in order when applicable:

1. A concise query in the caller's language.
2. An English equivalent.
3. English help-center title keywords.
4. A positive-only query that omits explicitly excluded products or paths.

The model-generated query array remains the semantic retrieval input. It is not
trusted as the sole workflow-state representation: Luna can occasionally write
a query for the generic step it expects to take next instead of the branch the
caller is actually in. Before preemptive generation begins, the worker therefore
captures a separate bounded `turnContext` from the authorized chat context. It
contains the latest caller utterance, the most recent structured-value length,
and allowlisted call metadata such as caller country. Long numeric values are
replaced with their digit count, and unrelated session metadata is excluded.
`turnContext` stays outside the embedding batch and is used only to focus the
canonical instruction excerpt on the active branch.

The same redaction is enforced on the model-generated query array before the
backend or embedding provider receives it. Prompting Luna to omit a raw
reference is useful, but it is not treated as a privacy boundary: any run of
four or more structured digits becomes a count marker such as
`[10-digit structured value]` while product and branch terms remain intact.

The backend embeds the array in one request, restores provider response order by
embedding index, and searches instruction and knowledge candidates independently
for every embedding. At most two query variants search concurrently to protect
the database pool; all variants are still evaluated. The merge combines
reciprocal rank with cross-query consensus, preserves represented source
categories, deduplicates candidates, and applies a deterministic final rank.
Instruction and knowledge allowlists remain independent and strict. No
selection means all content in that category is searchable.

## Grounding and context

The final rank reserves space for both source categories when both have relevant candidates. A calibrated relevance rule may return `no_match` even when vector search returned nearby documents. Results expose no internal score to the model; score and candidate diagnostics go to telemetry.

The worker keeps only a small per-call cache of read-only searches keyed by normalized query arrays. It does not preload source content. A cached request is single-use and can be consumed only by a tool execution with exactly matching arguments. At most three speculative requests may remain in flight; pending requests are never evicted merely to start more backend work. Discarded preemptive generations cannot update call state. A follow-up query may include the IDs returned by the immediately preceding successfully executed search so the backend can pin those authorized sources into the candidate set. The backend revalidates every pinned ID against the current instruction/knowledge scope and contact segments.

Instruction results are rendered from the current canonical instruction, never
from a stale vector chunk. Secondary instructions contain only the section that
matches the current branch. The primary instruction also contains the nearest
numbered workflow prerequisite: Step 1 may include Step 2, while a later step
includes its immediately preceding step. This preserves required lookup calls
without exposing an unrelated later troubleshooting branch early. A streamed
question is a hard runtime boundary: once the model asks the caller a question,
dependent tool calls later in that generation are suppressed and must wait for
the caller's next turn.

Structured-value ranking recognizes both numeric and spoken-word count phrases
such as “exactly 8 digits” and “eight-digit confirmation.” An exact-count branch
is promoted, while a title that explicitly describes fewer, more, invalid, or
wrong values at that same count is penalized. Result order remains a relevance
hint rather than an authorization boundary: an exact trigger in a later result
overrides an unrelated earlier result, but never permits skipping a prerequisite.

The backend gives embeddings a four-second tail budget inside a 5.5-second
absolute search deadline; the worker aborts at six seconds, leaving transport
headroom. These are ceilings, not delays. Successful K=10 TicketSwap tool calls
remained 721 ms p50 and 1,567 ms p95. The OpenAI Responses adapter also converts
LiveKit's exact function-choice shape to the provider's expected shape so the
forced search contract works on both supported OpenAI API modes.

The multi-query wire change is an intentional backend/worker contract break, so
the voice contract version and deployment guard are bumped together. This keeps
an old worker expecting singular `query` from deploying against a backend that
requires `queries`, and vice versa.

## Search-first enforcement

Before the initial LLM generation for a substantive caller turn, the worker forces `search_knowledge` when the agent has the reserved search tool and no search result follows the latest caller message. Greetings, short acknowledgements, single survey/keypad answers, and farewells are exempt. Long structured values such as reference numbers are substantive. After the search result, normal automatic tool selection resumes.

## Workflow reliability

Search hardening ships first and the focused Luna evals are rerun before workflow changes. Remaining authentication, troubleshooting, and survey failures must be reproduced by focused tests. Reusable state belongs in worker/backend orchestration, not org-specific prompt branches. Tool results should expose a typed next action, required input, and attempts remaining where the underlying workflow contract can support them. A survey controller owns the active question, answer binding, handoff lock, and exactly-once submission.

## Output and harness reliability

Spoken digit sequences, telephone numbers, and initialisms use deterministic formatting before TTS. Terminal tool-only turns are recorded as valid tool outcomes by the eval harness; latency evaluation does not require a streamed sentence when the turn is intentionally terminal.

The production-derived MoneyGram scenarios exposed three harness defects that
were not model failures: caller-role wording was too narrow, confirmation was
checked after field-entry prompts, and the C V V evaluator rejected the natural
compact spelling. Those parsers now accept production-equivalent wording. The
remaining ten-digit failures were a real retrieval/context gap: the correct
instruction reached the model, but a model-generated query and a broad secondary
instruction could advance to sender/receiver troubleshooting before the exact
money-order/money-transfer branch completed. Separate turn context plus
section-scoped instruction output raised that focused Luna gate from 7/10 to
10/10 (`voice-search-moneygram-ten-digit-luna-k10-v6-20260826`).

## Verification

Every production change follows red-green-refactor. Unit and focused integration tests run without starting, stopping, or killing external workers. Eval order is focused Luna K=1, full Luna K=1, focused Luna K=10, then the Luna-only K=10 gate. All gating scenarios must pass 100%.


# 2026 09 24 editor html migration design
Source: https://docs.open.cx/superpowers/specs/2026-09-24-editor-html-migration-design



# HTML documents and expanded editing

## Goal

Help Center content is HTML end to end: dashboard authoring, drafts, versions, translations, generated articles, search previews, knowledge-base synchronization, site reads, public APIs and MCP tools. There are no runtime Markdown imports, exports, fallbacks or stored projections.

## Storage

Source versions, locale versions and drafts carry `content_html`. The migration adds the column, converts only rows without HTML (preserving existing HTML, including empty strings), then removes `content_markdown` and its generated hashes. The legacy conversion lives under the database migration utilities; application code never imports it. Both migration directions take a ten-second lock timeout. Rollback writes the complete body back into the previous field as embedded HTML.

## Contracts

Public requests and responses use `content_html`. Create and update may omit it for metadata-only changes; draft saves require it, and `null` or an empty string clears the body. Markdown request fields are rejected. Sanitization keeps supported rich formatting and article references and strips executable markup. Search and reading time derive visible text from the HTML; no text column is stored.

## Editors

The Help Center editor exchanges `getHTML()` with the draft store and never re-sanitizes on the typing path. Acknowledging our own draft save does not reload the working copy, so selection, caret and undo history survive autosave. AI instructions keep their HTML marker and the import path for unmarked historical content. Shared non-document composers are unchanged.


# Manage teams and categories
Source: https://docs.open.cx/teams

Find and organize support teams with search, support status filters, and workspace categories. Edit team settings and manage members from one table.

Open **Settings → Teams** to find and manage teams in your workspace. Viewing this page requires **Teams** read permission. Creating categories, editing teams, and deleting teams require **Teams** write permission.

## Find a team

Search by team name, description, or category name. Select **Filters** to narrow the list by **Support status** or **Category**. Search and filters work together. Remove a filter using its label or select **Clear filters** in the filter menu.

The table shows **Team**, **Support status**, **Category**, and **Actions**. Labels beneath the team name show its member count and, for support-enabled teams, office hours and assignment settings. Existing team settings remain available in the editor.

## Organize teams into categories

1. Select **Create category** and enter a name, such as **Telephony** or **Chat**.
2. Select the pencil beside a team, or select **Add Team** to create one.
3. Choose a **Category** and select **Save** when editing. You can also create a category from this picker.

Each team can belong to one category. Choose **Uncategorized** to remove its category. Categories belong to the current workspace and remain available even if no team uses them. Reusing a category name, ignoring capitalization and surrounding spaces, reuses the existing category.

Categories organize teams in this list. They do not change team membership, support availability, session assignment, or call routing. A category called **Telephony** does not enable calling for its teams.

## Edit or delete a team

Select the pencil to open the existing team editor. Use **Details** for settings or **Members** to manage membership.

Select the red trash icon to request deletion. The confirmation names the team and describes the membership impact. **Cancel** leaves the team unchanged; **Delete** confirms the action.

## Choose session assignment order

Session assignment order is available for native OpenCX ticketing after a workspace admin turns on **Enable session priority** under **Settings → Workspace → Session priority**. The workspace setting is off by default. Editing the team requires **Teams** write permission. It is not connected to external ticketing integrations.

1. Select the pencil beside a team and open **Details**.
2. Enable support and select **Least busy** assignment.
3. Choose **Session assignment order** and select **Save**.

| Setting | What gets assigned first |
| - | - |
| **Longest waiting** | The existing waiting order. This is the default for every team. |
| **Priority first** | Higher priority, then the earliest outstanding SLA deadline, then the longest wait. |
| **SLA first** | The earliest outstanding SLA deadline, then higher priority, then the longest wait. |

Waiting starts at handoff when available, otherwise at session creation. Priority follows the workspace’s **Priority order**, including custom levels. The initial order is **Urgent**, **High**, **Medium**, **Low**, then **None**. Workspace admins can move custom levels above standard levels or reorder the standard levels; **None** stays lowest.

SLA ordering considers outstanding first-reply, next-reply, and resolution deadlines. Earlier deadlines come first, including overdue deadlines. Paused, completed, and snoozed SLA timers do not contribute a deadline. Sessions without an outstanding deadline follow those with one at the SLA comparison step.

The order applies within this team by default and preserves agent availability, capacity, office hours, and assignment pacing. It does not change who already owns a session, manual assignments, or live-call routing. Settings take effect on subsequent assignment passes. Choose **Longest waiting** to return to the existing behavior.

For example, **Priority first** puts a new Urgent session ahead of an older Low session. **SLA first** puts the Low session first if its outstanding deadline is earlier. A custom **VIP** level placed above **Urgent** takes precedence under **Priority first**. Under **SLA first**, the deadline still takes precedence. Set priority before assigning a session to the team when using a workflow.

Turning **Enable session priority** off returns teams to **Longest waiting** without erasing their saved assignment order. Re-enabling restores that order. Configure this setting in the dashboard. It is separate from the Inbox's display sort.

## Prioritize across teams

Workspace admins can enable **Prioritize across Priority-first teams** under **Settings → Workspace → Session priority**. This requires **Enable session priority** and native OpenCX sessions. It is off by default.

When an agent serves several **Priority first** teams, automatic assignment compares the eligible waiting sessions across those teams using the workspace priority order, then SLA deadline and waiting time. Each team keeps its own assignment delay, availability and capacity settings. A session the agent cannot currently receive does not block eligible work in another team.

Teams using **SLA first** or **Longest waiting** do not participate in this comparison. Set all teams you want compared to **Priority first**. Explicit agent assignments and sessions already owned by an agent are unaffected. Turning either workspace priority switch off restores per-team assignment; saved priorities and team settings remain.

## Configure teams with Companion

Companion can create teams with their settings, manage team names and membership, and change support enablement, office hours, assignment strategy, assignment pacing, and call settings. It can also create and list team categories, assign a category, or clear it. It follows your permissions; team changes require **Teams** write access.

For example, ask: “Create a Telephony category and assign the Sales team to it” or “Set Support to least-busy assignment with 30 seconds between assignments.” Companion can look up categories and office hours before assigning them. Unmentioned settings stay unchanged. See the [team tools](/mcp/tools) for the supported fields.


# Structured Fields
Source: https://docs.open.cx/ticketing/structured-fields

Create typed fields and nested choices once, then fill session values from the Inbox, workflows, or the API, and contact values through workflows or the API.

Structured Fields give your team a shared, typed vocabulary. Define a field once and fill it on sessions and on contacts: a session records what it was about, a contact keeps facts that carry across sessions, such as plan or tier. Use a simple field such as a date, or organize choices into a tree.

<Tip>
  Open [**Settings → Structured Fields**](https://platform.open.cx/settings/structured-fields) to create your first field.
</Tip>

## Create a field

<Steps>
  <Step title="Add the field">
    Click **New structured field**, then enter its name and description.
  </Step>

  <Step title="Choose its type">
    Use **Enum** for authored choices. Text, Number, Boolean, and Date hold workflow values; User, Team, and Tag read their choices from your organization.
  </Step>

  <Step title="Check the API name">
    The API name is generated from the field name. It cannot change after creation because workflows use it as the field's stable identifier.
  </Step>
</Steps>

## Build nested choices

Enum fields show an **Add top-level choice** button. Hover over any choice and click **+** to add a child below it. Each choice has a name, description, and immutable API value.

Only leaf choices are workflow outputs. For example, leaves with API values `refund` and `invoice` resolve as `refund||invoice`; parent choices only organize the tree.

## Use an enum for a session attribute

Expand an enum and choose **Link a session attribute**. Pick an existing session attribute, such as `__classification`, or enter a new exact key, then choose **Link attribute**. Enable **Show when empty** if agents should see it before a value has been recorded.

Use **Link another session attribute** to reuse the choices for an additional attribute. Each attribute can use only one enum.

The session sidebar uses this enum's choices as a searchable dropdown. Maintain choices here; there is no second list to configure. Selecting a choice saves its API value to the linked attribute, while other attributes retain their normal appearance. The link uses the enum as a choice list; it does not change its per-session structured field values or **Show when** rules.

You need Structured Fields editing permission to manage links and session editing permission to select a value. Unlinking an attribute leaves its session values intact. See [session attribute dropdowns](/inbox/dropdown-attributes) for duplicate-key handling, permissions, and troubleshooting.

## Show a field only when another field matches

A field can depend on another one. Open the field, choose **Show when**, pick a parent field (an Enum or Boolean field) and the choices that should reveal it.

| Field | Type | Shows when |
| - | - | - |
| Type | Enum: Bug, Feature request | always |
| Module | Enum: Payments, Inventory | Type is **Bug** |
| Priority | Enum: Low, Medium, High | Type is **Feature request** |

When an agent picks **Bug**, the Module field appears; picking **Feature request** shows Priority instead. Each dependent field stays a full field of its own, with its own name, filter, and workflow variable.

A field whose condition is not met is **not applicable** for that session or contact: it holds no value, is never required to close, and is cleared automatically if the parent changes. Dependent fields can chain up to five levels deep.

<Tip>
  Use nested choices for a category path inside one value (Billing → Refund). Use **Show when** for a separate field that should appear after an answer.
</Tip>

## Organize fields into groups

Groups split your fields into sets, for example **QA** for review fields and **Session details** for what the session was about. Click **New group** and give it a name and, optionally, a description that appears when you hover the icon next to the group's name. Then add fields from the group's **+** button or pick a **Group** when you create or edit a field. Fields without a group are listed under **Ungrouped**.

Groups only organize fields. A field works the same way in any group: in workflows, filters, exports, and the close form, where required fields are listed under their group's name.

* **Show when stays inside a group.** A field can only depend on a field in the same group, so the **Show when** picker lists only that group's fields.
* **Linked fields keep their group.** A field that another field depends on, or that depends on another field, cannot move to a different group. Remove the **Show when** condition, move the fields, then add it back.
* **Only empty groups can be removed.** Move or remove a group's fields before removing the group.

## Use fields in workflows

Reference a field with `{{structuredFields.<api_name>}}` or choose one of the Structured Fields actions:

| Action | Use it to |
| - | - |
| **Set Session Structured Field Value** | Record or clear one field's value on a session. |
| **Fill Structured Fields with AI** | Let the AI read a session's messages and record the values they support. |
| **Set Contact Structured Field Value** | Record or clear one field's value on a contact. |
| **Fill Contact Structured Fields with AI** | Let the AI read a session's messages and record the values they support on the session's contact. |
| **Set Structured Field Value** | Set or clear a Text, Number, Boolean, or Date field's own value for the whole workspace, separate from session and contact values. |
| **Update Structured Field or Choice** | Rename, redescribe, or remove a field or enum choice. |

### Record a value on a session

**Set Session Structured Field Value** takes a session number, a field, and a value: a leaf choice's API value for an Enum field, an id for a User, Team, or Tag field, `YYYY-MM-DD` for a Date. Leave **Value** empty to clear the field.

The value follows the same rules as the inbox. A value on a field whose **Show when** condition is not met fails the run and names the parent it is waiting on, so set the parent first. Changing a parent clears the dependent fields that no longer apply; the action lists them under **Removed Field Keys**.

### Fill fields from the session's messages

**Fill Structured Fields with AI** reads the session and its messages, then records a value for each field they support. Pick the fields to fill, or leave **Structured Fields** empty to fill every Enum, Text, Number, Boolean, and Date field. User, Team, and Tag fields are never filled by AI, so the picker does not offer them.

* **Parents come with their children.** If you pick a field that shows only when another field matches, that parent is added to the run when it is empty and listed under **Auto-included**; it is recorded only if the messages support it. A parent you did not pick is never changed once it holds a value.
* **Existing values are kept.** Fields that already hold a value are left alone unless **Overwrite Existing Values** is on. When an overwritten parent changes, dependent fields that no longer apply are cleared and listed under **Cleared**.
* **Nothing is guessed.** A field the messages do not support stays empty. Every field that was not recorded is listed under **Skipped** with its reason, such as `no_evidence`, `already_set`, `not_applicable`, `changed_concurrently` (someone recorded the field while the AI was reading), or `too_large` (the field has more choices than the AI can review at once).
* **Instructions** add guidance for this run, for example how your team tells a refund from a cancellation.

### Record values on a contact

**Set Contact Structured Field Value** takes a contact ID, a field, and a value, with the same value rules as the session action. **Fill Contact Structured Fields with AI** works like the session version, but records what the session's messages support on the session's contact instead of the session. The run fails when the session has no contact.

## Require fields before closing a session

Open [**Settings → Workspace → Closing sessions**](https://platform.open.cx/settings/workspace), turn on **Require Structured Fields to close**, and pick the fields agents must record.

When an agent moves a session to a closed status from the inbox, a form asks for the selected fields first. The session stays open until every one of them is filled. Values are saved per session and pre-filled if the agent comes back later.

To give a team different requirements, click **Add team** under **Team exceptions**, pick the team, and choose its own fields. For example, Billing agents also record an invoice number, while Support agents record the product. Turn off **Also require workspace fields** for a team that should skip the workspace list; with no fields of its own, that team closes sessions without the form. Teams not listed use the workspace list. A session follows the team it belongs to when it is closed, and a session without a team uses the workspace list.

Only human agents are affected. Sessions closed by the AI agent, by workflows, or by connected systems are not held back. A required field whose **Show when** condition is not met does not block a close; it is asked for only once its parent field holds a matching value.

## Values on a session

The values agents record are stored per session and mirrored into the session's attributes, so they appear in inbox filters, exports, and connected ticketing systems. They are also available through the [public API](/api-reference) and the [MCP tools](/mcp/tools) under the session's structured field values.

For attributes linked to an active enum through **Link a session attribute**, Session data takes precedence if the key exists in both attribute stores. The duplicate in Agent-added data is removed when an agent saves a dropdown selection. Ordinary session writes leave it unchanged. This does not change the Structured Field’s own per-session record or how unlinked attributes are handled.

## Values on a contact

The same fields can be filled on a contact. A contact holds its own values, separate from any of its sessions: setting a field on a contact never changes a session, and the other way around. The same value rules and **Show when** conditions apply.

Record them with the **Set Contact Structured Field Value** and **Fill Contact Structured Fields with AI** workflow actions, the [public API](/api-reference/contacts/set-structured-field-values), or the [MCP tools](/mcp/tools). Reading and writing through the API needs the contacts read and write scopes.

Contact values are kept with the contact only. They are not shown in the dashboard yet, do not appear in contact filters, segments, exports, reports, or connected CRMs, and are not copied into the contact's attributes.

## Limits

| | Limit |
| - | -: |
| Structured fields per organization | 50 |
| Groups per organization | 50 |
| Choices per enum field | 1,000 |
| Choice nesting depth | 10 levels |

***

## Related Documentation

<CardGroup>
  <Card title="Agentic Workflows" icon="robot" href="/build-agents/get-started">Build and run customer-support workflows.</Card>
  <Card title="AI Actions" icon="bolt" href="/actions/introduction">Let agents take action in connected systems.</Card>
  <Card title="Action Execution" icon="diagram-project" href="/actions/execution">Understand how workflow actions run.</Card>
  <Card title="MCP Tools" icon="wrench" href="/mcp/tools">Use OpenCX tools from an MCP client.</Card>
</CardGroup>


# Connect X (Twitter)
Source: https://docs.open.cx/twitter/connect-twitter

Bring your own X developer app, paste its credentials into OpenCX, and answer direct messages and public mentions with AI.

OpenCX connects to X through **your own X developer app**. You create the app on X, paste four
credentials into OpenCX, and authorize each brand handle you want to support.

<Note>
  Because the app is yours, **X bills you directly** for API usage and the app's rate limits are
  yours alone. OpenCX never sits between you and X's billing.
</Note>

## Before you start

You need an X account with a verified email and phone number — that account will own the developer
app permanently.

<Warning>
  Use a **company-owned X account**, not a personal one. Apps cannot be transferred between accounts
  later.
</Warning>

## 1. Create the app on X

1. Sign in at [console.x.com](https://console.x.com) and complete the developer signup.
2. Create an app, giving it a name and a description of your support use case.
3. Open the app's **User authentication settings** and set:
   * **App type:** Web App / Automated App (a confidential client)
   * **App permissions:** Read and write **and** Direct Messages
   * **Callback URL:** the value OpenCX shows you in the connection dialog
   * **Website URL:** your company site

<Warning>
  Set **App permissions before generating any credentials**. X bakes permissions into tokens at the
  moment they are issued, so credentials created before you enable Direct Messages will not be able
  to read or send DMs — you would have to regenerate them.
</Warning>

## 2. Add credit and a spending limit

X's API is pay-per-use. In the console, add a payment method and buy credits, then set a
**spending limit per billing cycle** and, optionally, auto-recharge.

<Note>
  If your credits run out or your spending limit is reached, X stops accepting messages. OpenCX
  surfaces this as a banner on the channel page and marks the affected replies as failed, but the
  fix always happens in your X console.
</Note>

## 3. Paste the credentials into OpenCX

In OpenCX go to **Channels → X (Twitter) → Add app**. All four values live on the app's
**Keys & Tokens** tab on X, split across two blocks:

| OpenCX field | Where to find it on X |
| - | - |
| API Key | **OAuth 1.0 Keys → Consumer Key** (reveal with the eye icon) |
| API Key Secret | Revealed together with the Consumer Key |
| OAuth 2.0 Client ID | **OAuth 2.0 Keys → Client ID** |
| OAuth 2.0 Client Secret | **OAuth 2.0 Keys → Client Secret** (reveal with the eye icon) |

<Note>
  X's naming is inconsistent: the credential we call **API Key / API Key Secret** appears in the
  console as **Consumer Key**, filed under a heading that says **OAuth 1.0 Keys**. Use it anyway —
  OpenCX authenticates accounts with OAuth 2.0, but X signs webhooks with the consumer pair, so both
  blocks are needed.
</Note>

You do **not** need the **Bearer Token** or either **Access Token** on that page. OpenCX derives its
own app-only bearer from the Consumer Key pair, and account tokens come from the OAuth redirect in
the next step.

If a secret was never saved and the eye icon only reveals the key, press **Regenerate** on that
block — it shows both values once. Regenerating invalidates the previous pair, so do it before
connecting accounts, not after.

OpenCX validates the credentials and registers a webhook on your app before saving. Two failures are
worth knowing about in advance:

* **"X rejected these API credentials"** — the API Key or Secret is wrong, or was regenerated after
  you copied it.
* **"Your X developer account already has a webhook registered"** — X allows one webhook per
  developer account on pay-per-use. Remove the existing one in the console, or use a separate
  developer account for OpenCX. OpenCX will never delete a webhook it did not create.

## 4. Connect your handles

With the app saved, choose **Add account** and authorize the brand handle on X. You can connect
several handles to one app.

If the authorization comes back missing a permission, OpenCX refuses the connection and names the
missing scope — fix **App permissions** on X, regenerate, and try again.

Direct messages start flowing immediately, and the AI answers according to your
[autopilot settings](/dashboard/introduction) for the X channel.

## 5. Public mentions (optional)

Replying publicly when someone mentions your handle is **off by default**. Turning it on opens a
checklist you must confirm, because X places these requirements on the account, not on OpenCX:

* The handle has the **Automated** label enabled (X → Settings → Your account → Account information
  → Automation).
* The account bio discloses automation, for example *"AI support by @yourcompany"*.
* You have **X's prior approval to deploy AI-generated replies**, requested through the
  [Policy Support form](https://help.x.com/forms/platform).

<Warning>
  X's developer guidelines state that deploying AI-generated replies without prior approval is a
  violation even when the replies are helpful. Confirm the checklist before enabling mentions.
</Warning>

Once enabled, the AI replies only to posts that explicitly mention the receiving handle and honors
opt-out phrases such as "stop".

### Reply to mentions as

To use a support handle for public replies to another brand handle, open **Channels → X** with
permission to manage channel settings. On the receiving account's card, enable public mentions,
then choose **Reply to mentions as**:

* **This account** (default): reply from the handle that received the mention.
* **Another connected account**: reply from that handle when the customer's post also mentions it.
  Only accounts connected to the same app are available.

Confirm the automation notice when choosing another handle, then click **Save**. The setting
applies to both AI and agent replies, including existing sessions. Each account's choice is
independent: replies use the chosen handle directly, even if that handle has its own different
reply setting.

X only accepts a reply from an account the post mentions. When a post mentions the receiving
handle but not the chosen handle, the reply comes from the receiving handle instead. For example, if
your brand account replies as your support handle, a post mentioning both handles gets a reply from
the support handle, and a post mentioning only the brand handle gets a reply from the brand handle.

Direct messages always use the account that received them. The **AI replies to DMs** switch is
independent of the public reply identity. In a public mention session, the inbox shows
**Replying as @handle** above the composer for the session's latest customer post.

<Warning>
  X's automation rules require the author to have summoned the automated account. Acknowledging the
  notice does not grant permission from X. Confirm that your intended use is permitted before
  enabling it.
</Warning>

If the selected reply account disconnects or moves to another app, affected public replies pause.
The account card shows **Public replies are paused**. Reconnect the same handle to the same app,
or select another reply account and save. While replies are paused, OpenCX doesn't fall back to the
receiving brand account, even for posts that don't mention the selected account. Changing the selection to **This account** explicitly restores that behavior.

## Encrypted messages

X moved direct messages to XChat, which is end-to-end encrypted. Encrypted chat in OpenCX is
**opt-in and always starts from your side**:

1. The account holder sets up **Chat in the X app** on the handle first, choosing a 4-digit PIN.
2. In OpenCX, on the channel page, enter that PIN for the handle and confirm.

Entering the PIN joins OpenCX to the handle's existing encrypted-chat identity **as an additional
device** — X allows any number of devices, so Chat in the X app keeps working exactly as before.
OpenCX **never creates, replaces, or resets encryption keys**, and it never touches the handle's
key backup. There is nothing to set up on our side and nothing we do behind your back.

You can enable encrypted chat at connect time or at any later point — the PIN entry stays
available on the channel page for every handle that has not enabled it yet.

A handle **without** XChat keeps working on unencrypted direct messages. One caveat: it **may not
receive DMs from users who have migrated to XChat** — if that starts happening, OpenCX shows a
banner on the channel page ("encrypted messages are arriving that OpenCX can't read"), and
entering the PIN is the fix.

<Warning>
  Each PIN entry is checked once against X's key backup, and **repeated wrong PIN entries can
  permanently destroy that backup** for the account. Verify the PIN in the X app before entering
  it — OpenCX never retries a PIN on its own and blocks further attempts for an hour after three
  failures.
</Warning>

## Delivery status

Agent and AI replies show a delivery state in the inbox, the same as WhatsApp: a single check when
sent, blue checks when the customer has read it, and a red icon when X rejected the message — hover
it for X's reason, such as a message flagged as spam or a recipient whose encryption keys changed.


# OpenCX Documentation
Source: https://docs.open.cx/welcome

AI-powered customer support - chat, phone, email, WhatsApp, SMS, and web.

<div>
  <div>
    <p>
      Guides, API references, and examples to help you deploy AI agents across every channel your customers use.
    </p>

    <Tip>
      First time here? Follow the **[Quickstart](/quickstart)** to get a live AI agent on your site in under 10 minutes.
    </Tip>
  </div>

  <div>
    <IntegrationOrbit />
  </div>
</div>

## Build AI Agents

Pick the channel your customers reach you on. Each page walks you from zero to a live agent.

<Card title="Chat Widget" icon="message" href="/widget/introduction">
  Embed on your website. Fastest setup.
</Card>

<CardGroup>
  <Card title="Phone" icon="phone" href="/phone/introduction">
    Inbound and outbound AI voice agents.
  </Card>

  <Card title="Email" icon="envelope" href="/email/introduction">
    Forward support mail, AI replies from your domain.
  </Card>

  <Card title="WhatsApp" icon="whatsapp" href="/whatsapp/introduction">
    Answer customers on WhatsApp Business.
  </Card>

  <Card title="SMS" icon="comment-sms" href="/sms/introduction">
    Register a number, reply to texts automatically.
  </Card>
</CardGroup>

## Train Your AI

Curate help center articles and connect live knowledge so answers stay accurate.

<Card title="AI Actions" icon="bolt" href="/actions/introduction">
  Teach agents to call your APIs — lookups, updates, real work.
</Card>

<CardGroup>
  <Card title="Help Center" icon="compass" href="/help-center/overview">
    Write articles and organize them into topics. Your AI reads from these first.
  </Card>

  <Card title="Knowledge Sources" icon="database" href="/knowledge/sources/overview">
    Connect Zendesk, Notion, Confluence, Google Drive, or crawl any website.
  </Card>
</CardGroup>

## Connect Integrations

Wire helpdesks, stores, and CRMs so agents and humans share full context.

<CardGroup>
  <Card title="Helpdesks" icon="headset" href="/dashboard/introduction">
    Zendesk, Front, Intercom, Gorgias, Salesforce — hand off with full context.
  </Card>

  <Card title="E-commerce" icon="cart-shopping" href="/integrations/shopify/overview">
    Shopify order lookup, product search, and customer metadata.
  </Card>

  <Card title="CRMs" icon="users-viewfinder" href="/integrations/hubspot/overview">
    HubSpot, Salesforce — sync contacts and conversations.
  </Card>

  <Card title="All Integrations" icon="grid-2" href="/dashboard/introduction">
    Browse every supported platform.
  </Card>
</CardGroup>

## For Developers

Automate with the REST API, MCP, and webhooks from your own stack.

<CardGroup>
  <Card title="API Reference" icon="code" href="/api-reference/authentication">
    Sessions, contacts, actions, phone agents, email, and more.
  </Card>

  <Card title="MCP Server" icon="network-wired" href="/mcp/introduction">
    Operate OpenCX from Claude Desktop, Cursor, and VS Code.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/types">
    Listen to session events, handoffs, and CSAT responses.
  </Card>

  <Card title="Partner Program" icon="handshake" href="/partners/introduction">
    White-label OpenCX and resell to your customers.
  </Card>
</CardGroup>

***

## Related Documentation

Follow quickstarts, architecture, and cross-links when you need more depth.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Live agent in 10 minutes — widget, knowledge, autopilot.
  </Card>

  <Card title="How OpenCX Works" icon="diagram-project" href="/how-opencx-works">
    The five pieces every agent shares.
  </Card>

  <Card title="Build Agents" icon="robot" href="/build-agents/get-started">
    Pick a channel and go live.
  </Card>

  <Card title="Integrations" icon="plug" href="/dashboard/introduction">
    Connect helpdesks, CRMs, and e-commerce platforms.
  </Card>
</CardGroup>


# Create WhatsApp Agent
Source: https://docs.open.cx/whatsapp/connect-whatsapp

Go live with AI WhatsApp — connect your business account, register a number, subscribe webhooks, and enable the AI.

Connect your WhatsApp Business account to OpenCX entirely from your [OpenCX dashboard](https://platform.open.cx).

## Prerequisites

<Warning>
  You need a **<Tooltip>verified business portfolio</Tooltip>** (or a business website for verification) and **admin access** to your business manager before connecting.
</Warning>

* **Verified business portfolio** in your business manager.
* **Admin access** to the business manager that owns the WhatsApp account.

## What You Will Configure

1. **Connect account** — authorize OpenCX via <Tooltip>OAuth</Tooltip>.
2. **Register number** — select your business phone number in the dashboard.
3. **<Tooltip>Subscribe webhooks</Tooltip>** — ensure message delivery is active.
4. **Enable AI** — toggle <Tooltip href="https://platform.open.cx/settings/autopilot">Autopilot</Tooltip> on for the number.

## Go Live

<Steps>
  <Step title="Open WhatsApp Channel Settings">
    Go to **[Channels → WhatsApp](https://platform.open.cx/channels/whatsapp)** in your dashboard.
  </Step>

  <Step title="Choose Your Connection Path">
    <Tabs>
      <Tab title="New number">
        Select **New number** and proceed to the OAuth step. No migration needed.
      </Tab>

      <Tab title="Migrate from consumer app">
        Select **Migrate from consumer app**. Before proceeding:

        * Close the WhatsApp consumer app on your phone.
        * Turn off **two-factor authentication** (2FA) for the number.

        <Warning>
          In-app chat history from the consumer app **cannot be transferred** and will be lost after migration.
        </Warning>
      </Tab>

      <Tab title="Migrate from another provider">
        Select **Migrate from another provider**. You may need to disconnect the number from your current provider first. Check your provider's migration guide.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Complete OAuth">
    Click **Connect** to open the authorization flow in a new tab. Grant OpenCX access to your WhatsApp Business account and select the number to register.
  </Step>

  <Step title="Register Your Number">
    Back in the dashboard, your number appears under **[Channels → WhatsApp](https://platform.open.cx/channels/whatsapp)**. Click the **Register** button next to the number to complete registration.
  </Step>

  <Step title="Subscribe To Webhooks">
    Click the **Subscribe to webhooks** button next to the number to enable message delivery. Without this, inbound messages will not arrive.
  </Step>

  <Step title="Enable AI For The Number">
    Toggle the **AI** switch on for the number. This is a per-number control — you can have multiple numbers with different AI settings.
  </Step>

  <Step title="Send A Test Message">
    Message your number from a real WhatsApp account. The message should appear in the [inbox](https://platform.open.cx/inbox). If **[Autopilot](https://platform.open.cx/settings/autopilot)** is enabled for WhatsApp, the AI will reply.
  </Step>
</Steps>

<Info>
  WhatsApp AI has **two layers of control**: org-level [Autopilot](https://platform.open.cx/settings/autopilot) (enables/disables AI for all WhatsApp numbers) and a **per-number toggle** on the [channel page](https://platform.open.cx/channels/whatsapp). Both must be on for the AI to reply.
</Info>

## Related Documentation

<CardGroup>
  <Card title="Troubleshooting" icon="wrench" href="/whatsapp/troubleshooting">
    Missing replies, delivery failures, and error logs.
  </Card>

  <Card title="WhatsApp Flow" icon="route" href="/whatsapp/messaging-rules">
    Session matching, reply format, and outbound behavior.
  </Card>

  <Card title="Messaging Rules" icon="scale-balanced" href="/whatsapp/whatsapp-rules">
    24-hour reply window, templates, and CSAT.
  </Card>

  <Card title="Human Handoff" icon="user-group" href="/handoff/introduction">
    AI to human escalation — applies to WhatsApp sessions.
  </Card>
</CardGroup>


# Whatsapp overview
Source: https://docs.open.cx/whatsapp/introduction

Overview of the AI WhatsApp channel — receive messages on your business number, reply with Autopilot, send templates, and escalate to human agents.

Customers message your **WhatsApp business number**. The AI replies using your knowledge base and tools. When <Tooltip href="https://platform.open.cx/settings/autopilot">**Autopilot**</Tooltip> is on, replies are automatic. Your team sees all conversations in the shared [inbox](https://platform.open.cx/inbox).

<Tip>
  New here? Skim this page, then open **[Create WhatsApp Agent](/whatsapp/connect-whatsapp)** to go live.
</Tip>

## Core Functionality

<AccordionGroup>
  <Accordion title="Inbound Messages" icon="message-arrow-down">
    Text, images, video, documents, and voice notes arrive in real time. Voice notes are transcribed so the AI can read them. Location pins are converted to map links.
  </Accordion>

  <Accordion title="AI Responses" icon="robot">
    The AI replies with plain text, quick reply buttons (up to 3), list menus (up to 10 options), or CTA links — depending on the content. **Autopilot** controls which conversations get auto-replied.
  </Accordion>

  <Accordion title="Session Continuity" icon="link">
    Conversations stay threaded by customer phone number and business number. A returning customer picks up where they left off. WhatsApp is the only channel where the AI can recall context from prior resolved sessions.
  </Accordion>

  <Accordion title="Templates" icon="rectangle-list">
    Send approved template messages to reach customers outside the <Tooltip>24-hour reply window</Tooltip>. View and send templates from the dashboard or via the [WhatsApp API](/api-reference/whatsapp/send-template). See [Messaging Rules](/whatsapp/whatsapp-rules) for details.
  </Accordion>

  <Accordion title="Third-Party Integrations" icon="plug">
    Connect to Zendesk, HubSpot, Front, and others from the [integrations settings](https://platform.open.cx/settings/integrations).
  </Accordion>

  <Accordion title="Escalation" icon="user-group">
    When a customer needs a human, the conversation <Tooltip href="/handoff/introduction">escalates automatically</Tooltip>. Your agents reply from the inbox and the customer gets it as a WhatsApp message.
  </Accordion>
</AccordionGroup>

<Note>
  WhatsApp requires a **verified business portfolio** before you can connect. See [Create WhatsApp Agent](/whatsapp/connect-whatsapp) for prerequisites.
</Note>

## Integration Options

<Tabs>
  <Tab title="WhatsApp setup">
    Connect your WhatsApp Business account, register a number, and enable the AI.

    <Card title="Create WhatsApp Agent" icon="arrow-right" href="/whatsapp/connect-whatsapp">
      OAuth, number registration, webhook subscription, AI toggle.
    </Card>
  </Tab>

  <Tab title="Third-party integrations">
    Connect helpdesks and CRMs from the [integrations settings](https://platform.open.cx/settings/integrations).

    <AccordionGroup>
      <Accordion title="Zendesk" icon="headset">
        WhatsApp conversations sync with [Zendesk Messaging](/integrations/zendesk/sunshine-conversations). When the AI hands off, your agents pick up in their Zendesk inbox.

        <Note>Enable **Handle WhatsApp** in your Zendesk integration settings for the AI to process WhatsApp messages routed through Zendesk Sunshine.</Note>
      </Accordion>

      <Accordion title="Front" icon="inbox">
        WhatsApp threads appear in your Front inbox. Handoffs route directly to your Front team with the full AI conversation attached.
      </Accordion>

      <Accordion title="HubSpot" icon="users-viewfinder">
        Conversations sync to [HubSpot](/integrations/hubspot/overview), including WhatsApp threads. On handoff, your reps pick up in HubSpot with full context.
      </Accordion>

      <Accordion title="Other integrations" icon="grid-2">
        OpenCX also supports [**Intercom**](/integrations/intercom/overview), [**Gorgias**](/integrations/gorgias/overview), and [**Salesforce**](/integrations/salesforce/overview). See [All Integrations](/dashboard/introduction) for the current list.
      </Accordion>
    </AccordionGroup>

    <CardGroup>
      <Card title="Zendesk Integration" icon="headset" href="/integrations/zendesk/overview">
        Messaging setup and handoff.
      </Card>

      <Card title="All Integrations" icon="grid-2" href="/dashboard/introduction">
        Browse every supported integration.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

***

## Related Documentation

<CardGroup>
  <Card title="Create WhatsApp Agent" icon="plug" href="/whatsapp/connect-whatsapp">
    OAuth, number registration, and AI toggle.
  </Card>

  <Card title="WhatsApp Flow" icon="route" href="/whatsapp/messaging-rules">
    Session matching, reply format, and outbound behavior.
  </Card>

  <Card title="Messaging Rules" icon="scale-balanced" href="/whatsapp/whatsapp-rules">
    24-hour reply window, templates, and CSAT.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/whatsapp/troubleshooting">
    Missing replies, delivery failures, and error logs.
  </Card>
</CardGroup>


# WhatsApp Flow
Source: https://docs.open.cx/whatsapp/messaging-rules

How inbound WhatsApp messages are matched to sessions — delivery path, reply format, interactive messages, and cross-session memory.

Use **[Create WhatsApp Agent](/whatsapp/connect-whatsapp)** first if you have not connected your account yet. For diagnosing issues, see **[Troubleshooting](/whatsapp/troubleshooting)**. For reply window and template rules, see **[Messaging Rules](/whatsapp/whatsapp-rules)**.

<Tip>
  **WhatsApp Flow** covers how **OpenCX** processes messages after go-live. Setup steps stay on [Create WhatsApp Agent](/whatsapp/connect-whatsapp).
</Tip>

## Path Of A Message

```mermaid theme={"dark"}
flowchart LR
  A([Customer]) --> B[WhatsApp]
  B --> C[Webhook]
  C --> D[Match number]
  D --> E[Session]
  E --> F[AI reply]
  F --> G([Customer])

  style A fill:#1a5c20,color:#fff,stroke:#267a2e
  style G fill:#1a5c20,color:#fff,stroke:#267a2e
```

<Steps>
  <Step title="Customer Sends A Message">
    The customer messages your WhatsApp business number. Text, images, video, documents, voice notes, and location pins are all supported.
  </Step>

  <Step title="Message Delivered To OpenCX">
    The message arrives via webhook and is validated.
  </Step>

  <Step title="Match Number To Org">
    **OpenCX** matches the receiving business number to your org.
  </Step>

  <Step title="Find Or Create Session">
    The sender's phone number is matched against existing contacts. If a contact has an **open WhatsApp session** on this business number, the message continues it. Otherwise a new session is created. If no contact record exists, a new contact is created automatically.
  </Step>

  <Step title="AI Generates Reply">
    If <Tooltip href="https://platform.open.cx/settings/autopilot">**Autopilot**</Tooltip> is enabled and the per-number AI toggle is on, the AI generates a reply after a <Tooltip>short delay</Tooltip>. When Autopilot is off or the session is handed off, human agents reply from the [inbox](https://platform.open.cx/inbox) instead.
  </Step>
</Steps>

<Note>
  The thread in your [OpenCX dashboard](https://platform.open.cx) is the authoritative record. Session continuity is by **customer phone number** and **business number**.
</Note>

## Outbound Format

The AI chooses the best format for each reply:

| Format | When used | Limits |
| - | - | - |
| **Plain text** | Default for text-only replies | Link previews enabled |
| **Quick reply buttons** | 1–3 short options for the customer to tap | Max **3** buttons, **20** characters per button |
| **List menu** | 4–10 options the customer selects from | Max **10** rows, **24** characters per row title |
| **CTA URL button** | Reply contains a single actionable link | Body up to **1024** characters, button label up to **20** characters |

## Quick reply suggestions in workflows

In **Workflows**, add a **Reply to ticket** step and set **Quick Reply Suggestions**. Enter the session number, message, and optional button labels, such as **Track transfer**, **Cancel transfer**, and **Speak to someone**. You can also reference values from earlier steps. Save and activate the workflow when it is ready.

Selecting a suggestion sends its label as a normal customer reply in the session. The usual AI, human assignment, and workflow rules process that reply. The sending step does not wait for a selection or automatically branch to another step. Customers can still type their own response.

<Warning>
  **WhatsApp limits:** at most **3 buttons**, with **20 characters per label** and **1,024 characters of rendered message text**. Labels must be non-empty, unique, and plain text. A customer must have messaged your business number within the **24-hour reply window**. Outside that window, use **Send WhatsApp Template** with an approved template; this reply step cannot reopen the window.
</Warning>

The three-button and 20-character label limits apply to workflow suggestions on every supported channel, keeping the same workflow compatible with WhatsApp. Invalid values, including values supplied by earlier steps, fail the step instead of being truncated. Labels are sent as configured: supply them in the customer's language. If automatic message translation expands the WhatsApp body beyond 1,024 characters, the message is delivered as plain text without suggestions.

Suggestions also work in the **OpenCX web widget**, **Messenger**, and **Instagram**. Custom API clients can read message options but must render and submit selections themselves. WhatsApp, Messenger, and Instagram must be connected directly to OpenCX. Other channels and sessions whose replies are delivered through an external integration do not support workflow suggestions; the step fails before saving a reply. Leave suggestions empty to keep existing text-only behavior.

Users need permission to edit workflows. See [Workflows](/api-reference/workflows/index) for creating and validating workflows through the API.

## Good To Know

<AccordionGroup>
  <Accordion title="Cross-Session Memory" icon="brain">
    WhatsApp is the only channel where the AI pulls context from **<Tooltip>prior resolved sessions</Tooltip>** for the same customer and business number. This means the AI can reference earlier conversations without the customer repeating themselves.
  </Accordion>

  <Accordion title="Media Handling" icon="photo-video">
    Voice notes are **transcribed** so the AI can read them. Images, video, and documents are attached to the conversation. Location pins become map links. Stickers and system messages are not processed.
  </Accordion>

  <Accordion title="Outbound Attachments" icon="paperclip">
    Attachments are sent as separate messages (one per file) followed by the text reply. There is a short pause between each.
  </Accordion>

  <Accordion title="Session Auto-Resolution" icon="clock">
    WhatsApp sessions auto-resolve after approximately **12 hours** of inactivity by default — longer than web chat (3 hours). Contact support to adjust your org's threshold.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Troubleshooting" icon="wrench" href="/whatsapp/troubleshooting">
    Missing replies, delivery failures, and error logs.
  </Card>

  <Card title="Messaging Rules" icon="scale-balanced" href="/whatsapp/whatsapp-rules">
    24-hour reply window, templates, and CSAT.
  </Card>

  <Card title="AI Actions" icon="bolt" href="/actions/introduction">
    Run tools and workflows from WhatsApp conversations.
  </Card>

  <Card title="Autopilot And Topics" icon="sliders" href="/handoff/topics">
    Channel-level Autopilot and topic rules.
  </Card>
</CardGroup>


# Whatsapp troubleshooting
Source: https://docs.open.cx/whatsapp/troubleshooting

Fix common WhatsApp channel issues — missing replies, delivery failures, webhook problems, session-state issues, and template rejections.

Before debugging, have these ready: your **business number**, the **channel status** in your [OpenCX dashboard](https://platform.open.cx), and a **recent message** if available.

<Tip>
  Looking for setup steps? See [Create WhatsApp Agent](/whatsapp/connect-whatsapp). For routing logic, see [WhatsApp Flow](/whatsapp/messaging-rules). For reply window and templates, see [Messaging Rules](/whatsapp/whatsapp-rules).
</Tip>

## Common Troubleshooting Scenarios

| Symptom | Likely cause | What to do |
| - | - | - |
| **No AI reply** | Autopilot or per-number AI toggle is off | Check both: org-level [Autopilot](https://platform.open.cx/settings/autopilot) **and** the per-number toggle on [Channels → WhatsApp](https://platform.open.cx/channels/whatsapp). |
| **Message not in inbox** | Webhook subscription missing | Go to [Channels → WhatsApp](https://platform.open.cx/channels/whatsapp) and click **Subscribe to webhooks** if the warning appears next to the number. |
| **Outbound message fails** | Delivery error from the platform | Check the [error logs](https://platform.open.cx/channels/whatsapp/error-logs) for details. Common causes: invalid recipient number, rate limits, or account restrictions. |
| **Template not sent** | Template not approved or parameters missing | Verify the template is approved under [Channels → WhatsApp](https://platform.open.cx/channels/whatsapp) → **View templates**. Check that all required parameters are filled. |
| **Message shows as sent in OpenCX but the customer never receives it** | Meta accepted the request but did not deliver it | Check the [error logs](https://platform.open.cx/channels/whatsapp/error-logs) first. If you see send success without a corresponding delivery signal, review the template category, recent message volume, and any Meta account restrictions in Business Manager. |
| **AI stops replying after a human handled the conversation** | The WhatsApp session is still open or handed off in the helpdesk layer | If you use Zendesk Sunshine, make sure the conversation is fully ended in Zendesk, not only marked solved. When testing, start with a fresh customer message after the prior session has closed. |

<Info>
  If messages are not arriving in your dashboard, the problem is almost always the **webhook subscription** — not a platform outage.
</Info>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Why do WhatsApp messages fail even though the template is approved?" icon="rectangle-list">
    Approval is required, but it is not the only delivery check. Meta can still limit or suppress delivery based on template category, conversation health, recipient behavior, or account restrictions. If a template is business-critical, prefer a utility-style template where appropriate and check delivery logs after each send.
  </Accordion>

  <Accordion title="Why did the AI reply in OpenCX but not on the customer's phone?" icon="triangle-exclamation">
    That usually means OpenCX generated the reply, but WhatsApp did not complete delivery. Treat this as a delivery issue first, not an AI issue. Check the WhatsApp logs and your Meta Business Manager status before changing prompts or Autopilot settings.
  </Accordion>
</AccordionGroup>

## Limits

| Area | Detail |
| - | - |
| **Inbound delivery** | **Instant** via webhook. |
| **AI reply** | Typically **seconds** after a short debounce delay. |
| **Session auto-resolution** | Approximately **12 hours** of inactivity (org-level overrides possible). |
| **Reply window** | **24 hours** from last customer message. After that, only templates can be sent. |

## Error Logs

View delivery errors and API failures at **[Channels → WhatsApp → Logs](https://platform.open.cx/channels/whatsapp/error-logs)**. Filter by date range, business number, error type, or recipient phone number.

***

## Related Documentation

<CardGroup>
  <Card title="Create WhatsApp Agent" icon="plug" href="/whatsapp/connect-whatsapp">
    Re-check OAuth, number registration, and webhook subscription.
  </Card>

  <Card title="WhatsApp Flow" icon="route" href="/whatsapp/messaging-rules">
    Re-check session matching and delivery path.
  </Card>

  <Card title="Messaging Rules" icon="scale-balanced" href="/whatsapp/whatsapp-rules">
    Reply window expired? Check template requirements.
  </Card>

  <Card title="Autopilot And Topics" icon="sliders" href="/handoff/topics">
    Verify channel-level Autopilot and topic rules.
  </Card>
</CardGroup>


# Messaging Rules
Source: https://docs.open.cx/whatsapp/whatsapp-rules

WhatsApp platform rules — the 24-hour reply window, template messages, and CSAT for WhatsApp conversations.

<Tip>
  For setup steps, see [Create WhatsApp Agent](/whatsapp/connect-whatsapp). For routing and reply format, see [WhatsApp Flow](/whatsapp/messaging-rules).
</Tip>

## 24-Hour Reply Window

WhatsApp enforces a <Tooltip>**24-hour reply window**</Tooltip>. Free-form messages (text, media, interactive) can only be sent within **24 hours** of the customer's last message. After the window closes, only **approved <Tooltip>template messages</Tooltip>** can be sent.

| Situation | What you can send |
| - | - |
| **Within 24 hours** of last customer message | Any message — text, media, quick replies, list menus, CTA links |
| **After 24 hours** | Only **approved template messages** |

<Info>
  The dashboard shows the **reply window deadline** per contact so your team knows when free-form messaging expires.
</Info>

## Template Messages

Templates are pre-approved message formats registered with WhatsApp. Use them for proactive outreach, follow-ups, or any messaging outside the reply window.

<Info>
  A template being **approved** does not guarantee delivery. Meta can still restrict sends based on template category, account health, or recipient-level messaging limits. If a notification is operational in nature, prefer the appropriate utility-style template.
</Info>

### Viewing Templates

View your approved templates under **[Channels → WhatsApp](https://platform.open.cx/channels/whatsapp)** — click **View templates** next to any registered number.

### Organizing Templates

In **Channels → WhatsApp → View templates**, choose **Manage groups** to create,
rename, or delete template groups. Use the group selector on each template to
assign it to one group or leave it **Ungrouped**. Managing groups requires channel
settings write permission.

Groups are shared across your organization, independently of OpenCX Teams.
Deleting a group moves its templates to **Ungrouped**; it does not delete templates.

The **Send template** and **New Session** pickers show your personal **Most used**
templates first, followed by alphabetical, collapsible groups and **Ungrouped**.
Each template appears once. Search finds templates across collapsed groups and
also matches group names. Only templates available for the selected sending
account appear.

### Sending Templates

<Tabs>
  <Tab title="From the dashboard">
    <Steps>
      <Step title="Open The Conversation">
        Open the conversation in the [inbox](https://platform.open.cx/inbox).
      </Step>

      <Step title="Choose Send Template">
        If the free-form reply window has expired, choose **Send template**.
      </Step>

      <Step title="Pick And Send">
        Pick an approved template for the connected number, fill in the required parameters, and send.
      </Step>
    </Steps>

    Need to check available templates first? Go to **[Channels → WhatsApp](https://platform.open.cx/channels/whatsapp)** and click **View templates** next to the number. If sending still fails, see [Troubleshooting](/whatsapp/troubleshooting).
  </Tab>

  <Tab title="Via API">
    Use the [Send Template API](/api-reference/whatsapp/send-template) to send templates programmatically. Requires the <Tooltip>whatsapp:write</Tooltip> scope.

    **Required fields:** <Tooltip>`template_id`</Tooltip>, <Tooltip>`phone_number_id`</Tooltip>, <Tooltip>`variables`</Tooltip> (parameter values), and <Tooltip>`contact`</Tooltip> (id, email, or phone).
  </Tab>
</Tabs>

## CSAT

WhatsApp has a dedicated <Tooltip href="https://platform.open.cx/settings/csat">CSAT</Tooltip> toggle. When enabled, satisfaction surveys are sent to customers after resolved conversations. Configure CSAT under **[Settings → CSAT](https://platform.open.cx/settings/csat)**.

<Note>
  WhatsApp CSAT currently sends the customer to a survey link. It is not a fully native in-thread WhatsApp form.
</Note>

***

## Related Documentation

<CardGroup>
  <Card title="Create WhatsApp Agent" icon="plug" href="/whatsapp/connect-whatsapp">
    OAuth, number registration, and AI toggle.
  </Card>

  <Card title="WhatsApp Flow" icon="route" href="/whatsapp/messaging-rules">
    Session matching, reply format, and outbound behavior.
  </Card>

  <Card title="WhatsApp API" icon="code" href="/api-reference/whatsapp/send-template">
    Send template messages programmatically.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/whatsapp/troubleshooting">
    Missing replies, delivery failures, and error logs.
  </Card>
</CardGroup>


# OpenCX widget AI coding skills
Source: https://docs.open.cx/widget/agent-skills

Install OpenCX widget skills with npx to guide your coding assistant through a new integration, Companion setup or migration from v4 to v5.

OpenCX skills help your coding assistant install, configure, or upgrade the
widget. They work with assistants such as Claude Code, Codex, and Cursor.

Run the command for your task in your app's directory, then select your assistant
when prompted. You need Node.js and npm installed.

## Add or configure the widget

```bash theme={"dark"}
npx skills add opencx-labs/widget --skill opencx-widget-integration
```

Then ask your assistant:

> Use opencx-widget-integration to add the OpenCX widget to this app with v5
> and Companion mode. Exclude query strings, fragments, and private path or title
> data from page context.

Get your widget token from **Channels → Web chat** in your OpenCX dashboard.

## Upgrade from v4 to v5

```bash theme={"dark"}
npx skills add opencx-labs/widget --skill opencx-widget-migration
```

Then ask your assistant:

> Use opencx-widget-migration to upgrade our widget from v4 to v5. Check our
> custom components, authentication, and self-hosted assets. Exclude query strings,
> fragments, and private path or title data from page context.

See the [migration guide](/widget/migrate-to-v5) for the full upgrade checklist.

## Before applying changes

Skills give your assistant instructions. Installing one does not change your
website, upgrade the widget, or enable features in your workspace. Ask for an exact published version and have the assistant check the [current migration contract](/widget/migrate-to-v5), including opt-in delivery and page permissions.

Review the installed instructions and the code changes your assistant proposes.
If a skill suggests sending a full page URL, use the
[safe page-context examples](/widget/companion-mode#share-the-current-page) instead.

To get a newer skill, rerun its installation command and review the changes.
Keep the skill files and lockfile in version control with your app.

Prefer to set up the widget yourself? See [Install Widget](/widget/install-widget)
and [Companion mode](/widget/companion-mode).


# Authentication
Source: https://docs.open.cx/widget/authentication

Choose how the AI Chat Widget should recognize visitors, protect conversation history, and support signed-in customers.

Use this page when you need to decide who the widget should treat as the same person, and how much trust to place in the identity data you pass in.

<Tip>
  If your goal is to get the widget on the page first, start with **[Install Widget](/widget/install-widget)**.
</Tip>

<Info>
  Want to see how identity settings look on screen? The **[Playground](/widget/playground)** lets you toggle visitor data collection and other options live, then copy the matching snippet.
</Info>

## Start With The Right Identity Model

<AccordionGroup>
  <Accordion title="Anonymous visitor" icon="user">
    Lowest friction. Best for public support chat where history stays tied to the same browser.
  </Accordion>

  <Accordion title="Non-verified visitor" icon="id-card">
    Best when you want name, email, or lightweight personalization without server-issued identity.
  </Accordion>

  <Accordion title="Verified customer" icon="shield-check">
    Best when signed-in customers should keep history across devices and you need stronger protection against impersonation.
  </Accordion>
</AccordionGroup>

## What Changes Between Non-Verified And Verified

<AccordionGroup>
  <Accordion title="History access" icon="clock">
    Verified customers can keep history across devices. Anonymous and non-verified visitors should be treated as browser-bound or device-bound experiences.
  </Accordion>

  <Accordion title="Trust level" icon="shield">
    <Tooltip>`collectUserData`</Tooltip> and <Tooltip>`user.data`</Tooltip> help you personalize the chat, but they do not prove identity. <Tooltip>`user.token`</Tooltip> is the strong identity path.
  </Accordion>

  <Accordion title="Custom data handling" icon="database">
    Browser-provided custom data is useful, but should be treated with caution. Server-authenticated custom data is the safer choice when it affects support decisions.
  </Accordion>
</AccordionGroup>

## Two Tokens, Two Jobs

Do not confuse these tokens:

<CardGroup>
  <Card title="Widget token" icon="key" href="/widget/install-widget">
    This token loads your organization’s widget. Get it from the widget setup flow, then use it when you install the widget.
  </Card>

  <Card title="Authenticated contact token" icon="shield-check" href="/api-reference/widget/authenticate-contact">
    This token identifies a verified customer. Your backend requests it, then passes it to `user.token`.
  </Card>
</CardGroup>

## Implementation Paths

<Tabs>
  <Tab title="Collect">
    <Steps>
      <Step title="Choose this path for public visitors">
        Use this when visitors are not signed in and you want the widget to ask for basic details before chat begins.
      </Step>

      <Step title="Turn on built-in collection">
        Add `collectUserData: true` to the widget options.

        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          collectUserData: true,
        };
        ```
      </Step>

      <Step title="Test the welcome flow">
        Confirm the widget asks for the visitor’s name and email before they enter the chat.
      </Step>
    </Steps>

    <Note>
      This creates a **non-verified** identity. It improves context for your team, but it should not be treated as strong proof that the visitor owns that email address.
    </Note>
  </Tab>

  <Tab title="Browser">
    <Steps>
      <Step title="Choose this path for lightweight personalization">
        Use this when your app already knows who the visitor is and you want the widget to start with that information.
      </Step>

      <Step title="Pass the visitor data in user.data">
        Send the fields you already know from the browser.

        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          user: {
            data: {
              name: user.name,
              email: user.email,
              avatarUrl: user.avatarUrl,
              customData: user.customData,
            },
          },
        };
        ```
      </Step>

      <Step title="Use it for convenience, not proof">
        This is best when the widget should feel personalized, but you do not need strong identity guarantees.
      </Step>
    </Steps>

    <Note>
      This is still **non-verified** because the browser can be tampered with.
    </Note>
  </Tab>

  <Tab title="Server">
    <Steps>
      <Step title="Choose this path for signed-in customers">
        Use this when customers sign in to your product and should keep history across devices.
      </Step>

      <Step title="Request a verified contact token on your backend">
        Call the widget authentication API from your server.

        <CodeGroup>
          ```bash cURL theme={"dark"}
          curl -X POST https://api.open.cx/widget/authenticate-user \
            -H "Authorization: Bearer <ORG_API_KEY>" \
            -H "Content-Type: application/json" \
            -d '{
              "email": "jane@example.com",
              "name": "Jane Doe",
              "customData": {
                "plan": "enterprise",
                "accountId": "acct_123"
              }
            }'
          ```

          ```ts fetch theme={"dark"}
          const response = await fetch('https://api.open.cx/widget/authenticate-user', {
            method: 'POST',
            headers: {
              Authorization: 'Bearer <ORG_API_KEY>',
              'Content-Type': 'application/json',
            },
            body: JSON.stringify({
              email: user.email,
              name: user.name,
              customData: {
                plan: user.plan,
                accountId: user.accountId,
              },
            }),
          });

          const { token: authenticatedContactToken } = await response.json();
          ```
        </CodeGroup>
      </Step>

      <Step title="Pass the token into the widget">
        Use the returned token through `user.token`.

        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          user: {
            token: authenticatedContactToken,
          },
        };
        ```
      </Step>
    </Steps>

    <Tip>
      This is the recommended path for **signed-in customer support**.
    </Tip>
  </Tab>
</Tabs>

## Connect Each Customer's Account

For dashboard setup, the customer flow, and approval controls, see [Widget connections](/widget/connections). This section covers the backend authentication contract.

In **Actions**, add a server and choose **Each user — their own account**. Authenticate the signed-in customer through your backend as usual. By default, they can connect to every enabled per-user server in your organization:

```ts theme={"dark"}
// Run on your backend. Resolve the user from your authenticated session.
const response = await fetch('https://api.open.cx/widget/authenticate-user', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OPEN_CX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: user.email,
    name: user.name,
  }),
});
if (!response.ok) throw new Error('Could not authenticate the customer');
const { token } = await response.json();
// Return only this widget user token to your frontend.
```

To enable personal connections, include `mcp_access: {}` in the same request. To restrict a user or bind an account, provide:

```ts theme={"dark"}
mcp_access: {
  server_ids: allowedServerIds,
  account_id: account.id,
}
```

* Omit `mcp_access`: preserve the existing chat-only token without an expiry; personal connections are not enabled.
* Include `mcp_access: {}` or omit `server_ids` inside it: allow all enabled per-user servers in this organization, including servers enabled later.
* Set `server_ids` to a list: allow only those servers, while they remain enabled.
* Set `server_ids: []`: allow none.

Shared team connections and other organizations' servers are never included. Decide restrictions on your backend; never accept an unchecked list from the browser. `account_id` is optional for single-account products; include it when users can switch workspaces or accounts. Connections and session history are bound to that signed account. Browser custom data and `externalId` do not grant access.

Pass the result as `user.token`. Tokens issued with explicit `mcp_access` expire after **one hour**. Chat-only tokens issued without it retain their existing non-expiring behavior, including for Widget v4 integrations. For personal connections, have your frontend request a replacement from your authenticated backend before expiry—for example, after 50 minutes—and update the widget's `user.token`. A replacement for the same signed owner preserves the current session; changing the signed user or account starts a separate widget context. Renew promptly when returning to a suspended tab, and recheck permissions on every renewal. Existing chat-only tokens must be replaced using explicit `mcp_access` to enable personal connections. Existing chat-only integrations do not need to add token renewal or update their widget.

For the September 15 token-expiry incident, the backend restores chat access for affected, correctly signed tokens issued during the rollout with an empty personal-access grant. This recovery preserves the previous chat authentication behavior without requiring customer code changes, a widget update, or a page reload. It does not restore personal-tool access or apply to explicitly scoped account/server grants. Signature, organization, contact, and session ownership checks still apply.

When a tool needs access, the widget shows one **Connect** action. After approval it continues the request in the background. Users do not need an OpenCX dashboard account. Provider credentials stay on the backend; the organization API key must never be passed to the widget.

For customer-managed integrations, point the server definition at your authenticated gateway. Your gateway owns downstream provider credentials and permissions. The widget can open its setup page and retry the tool when the user returns; returning alone does not confirm access. Your gateway must verify the customer’s access when handling that retry. For a shared team account, choose **Our team — one shared account** and connect it in Actions instead.

Starting a new session clears the session’s messages and pending connection prompts, while keeping the same signed user/account’s saved connections. Connection controls and requests require `streaming: true` and `capabilities.connections: true` in Widget 5.0.0; omission keeps connections off. Enforce access restrictions separately through your backend’s `mcp_access` settings.

Ownership is fixed when the server is created. Changing a personal server's URL requires explicit acknowledgement that its users will need to connect again.

## Reuse a Customer Connection in Your Backend

Enable **Reuse connections in your backend** on a server configured as **Each user — their own account**. This is off by default. Enable it before the customer connects; existing connections need a successful reconnect to produce a readiness notification.

OpenCX completes the normal connection flow and manages encrypted credentials and refresh. Your backend receives a readiness notification and can retrieve the current access token. You do not need to build a gateway for this path.

1. Configure your webhook endpoint in **Settings → Webhooks** and subscribe to `connection.ready` if your endpoint filters events.
2. Create a backend API key with **Connection credentials → Retrieve access tokens** (`connections:tokens`). Keep it on your server.
3. Authenticate widget users as described above. Include `account_id` when accounts must be isolated.
4. After the user connects, verify the webhook signature using your endpoint's signing secret. Deduplicate on `event_id` and save the connection ID against the matching customer/account.
5. Retrieve the access token from your backend when needed.

Example webhook payload:

```json theme={"dark"}
{
  "event": "connection.ready",
  "event_id": "connection-ready-<event-id>",
  "organization_id": "<organization-id>",
  "data": {
    "connection_id": "<connection-id>",
    "server_id": "<server-id>",
    "contact_id": "<OpenCX-contact-id>",
    "account_id": "<your-account-id>",
    "revision": 1,
    "connected_at": "2026-09-15T12:00:00.000Z"
  }
}
```

`contact_id` identifies the OpenCX contact, not an email or your application's user ID. Map it to your authenticated customer before using the connection. `account_id` is the value supplied during authentication, or `null` when omitted.

```bash theme={"dark"}
curl --request POST \
  'https://api.open.cx/widget/connections/<connection-id>/access-token' \
  --header "Authorization: Bearer $OPEN_CX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"contact_id":"<OpenCX-contact-id>","account_id":"<your-account-id>"}'
```

Successful response (`201`):

```json theme={"dark"}
{
  "connection_id": "<connection-id>",
  "resource": "https://service.example.com/mcp",
  "access_token": "<current-access-token>",
  "token_type": "Bearer",
  "expires_at": "2026-09-15T13:00:00.000Z",
  "scope": "read write"
}
```

Omit `account_id` in the request when authentication omitted it. The organization, contact and account must all match. The API checks the connection with its service and uses the same refresh lock as agent calls. `expires_at` and `scope` are `null` if the service did not supply them. Only reusable bearer access tokens are supported; refresh tokens, client secrets and identity tokens are never returned. Widget user tokens cannot call this endpoint.

Use the access token only with the service/resource and permissions it was issued for. An MCP access token does not automatically grant access to a separate bookkeeping API. Reusing that API directly requires the provider to issue a token valid for it. Keep retrieved tokens on your backend, out of browsers and logs. OpenCX retains refresh ownership; retrieve a new access token when required instead of maintaining a second refresh loop.

Readiness events are saved with the grant and submitted in the background, normally within 30 seconds. Temporary submission failures retry; configured webhook delivery also retries failures at your endpoint. Delivery can be repeated, so handlers must be idempotent. Readiness describes a completed authorization, not a permanent guarantee of access. Reconnects produce a new event; routine token refreshes do not.

`403` means the API key or token type is not permitted. `404` means the connection does not match the requested owner or sharing is disabled. `409` with `connection_required` means the customer must reconnect. `502` means the connected service could not be reached or validated; retry later. Disabling sharing prevents future retrieval, and disconnecting removes the stored grant. Already retrieved access tokens can remain valid until they expire or are revoked by their issuer.

## Extra Identity Controls

### Scope History With `externalId`

Use <Tooltip>externalId</Tooltip> when the same person can belong to multiple accounts, workspaces, or tenants inside your product.

```tsx theme={"dark"}
const options = {
  token: '<WIDGET_TOKEN>',
  user: {
    token: authenticatedContactToken,
    externalId: currentWorkspaceId,
  },
};
```

This keeps history aligned to the right account context instead of treating every conversation for that email address as one shared history.

### Prefill Or Collect More Fields

`name` and `email` are the visitor details the widget can show or collect. <Tooltip>`prefillUserData`</Tooltip> fills those fields before the visitor types, while <Tooltip>`extraDataCollectionFields`</Tooltip> adds more fields to the collection form.

If you are using the widget’s built-in data collection flow, you can:

* prefill `name` and `email` with `prefillUserData`
* collect additional fields with `extraDataCollectionFields`

These are good onboarding improvements for public support flows, but they do not replace verified identity.

## API Notes For Server-Side Authentication

The widget authentication API is designed for your backend:

<CardGroup>
  <Card title="1. Call the endpoint" icon="code">
    Call `POST /widget/authenticate-user` from your backend.
  </Card>

  <Card title="2. Use the right API key" icon="key">
    Authenticate with an org API key that has <Tooltip>`widget:write`</Tooltip>.
  </Card>

  <Card title="3. Return or store the token" icon="database">
    Store the contact token in your app flow or return it to the frontend.
  </Card>

  <Card title="4. Pass it to user.token" icon="shield-check">
    Give the widget the verified token through `user.token`.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Widget Authentication API" icon="arrow-right" href="/api-reference/widget/authenticate-contact">
    Open the full API contract, request example, and response shape for authenticated contact tokens.
  </Card>
</CardGroup>

### If Your AI Actions Need Request Data

<Tooltip>`headers`</Tooltip>, <Tooltip>`queryParams`</Tooltip>, and <Tooltip>`bodyProperties`</Tooltip> do not identify the visitor. They add request data to the HTTP calls your AI actions make to your own APIs.

<Info>
  Use widget authentication to decide **who the visitor is**. Use action request fields to decide **what your AI action sends to your API**. If you need help with that second part, see [Authentication](/actions/authentication).
</Info>

## Renew identity without losing the active session

Widget 5.0.0 keeps the current session when you replace an OpenCX-issued `user.token` for the same signed owner and access scope. Renew through your authenticated backend and pass the new token into the existing `<Widget options={...} />`. For the HTML embed, call `initOpenScript` again with the complete current configuration and renewed `user.token`; keep the same root and mounted integration.

Changing the widget organization, signed contact, account scope or `externalId` resets the active widget state so the previous owner’s messages do not remain visible. On logout, remove the old verified token before showing anonymous chat. Returning to an account loads only that account’s permitted history. Opaque or unrecognized token formats use a conservative reset rather than assuming the owner is unchanged.

The widget does not mint replacement tokens. Chat-only authentication keeps its existing lifetime; upgrading the client does not introduce a new authentication endpoint or make polling require streaming. Test renewal and account switching with your real server-issued tokens, including after a tab has been suspended.

## MCP form requests

A connected MCP server can ask the authenticated user to complete a form inside the widget. The form identifies the requesting service and supports text, numbers, booleans, and single- or multiple-choice fields.

The user reviews the fields and chooses **Submit**, **Decline**, or **Cancel**. Multiple-choice fields enforce the server’s minimum and maximum selection counts and show a correction message without discarding the selections. Answers are checked against the server's schema and returned to the original tool call; the tool is not restarted. Requests expire after 50 seconds and cancel without approval. Only the matching user, account, and session can submit an answer.

For a simple approval request, users can choose **Approve once** or **Always allow** beside it. Remembered approval applies only to the same connected account, server, tool, inputs, and form. Changed requests still ask for approval. Other forms always require a response.

### Manage personal connections and approvals

From the widget session list, open **Connections** and select a service. This screen contains services connected by the signed-in user/account; shared administrator connections are not shown.

* **Saved approvals → Remove approval** removes one remembered approval. The next matching request asks again; the service stays connected.
* **Disconnect** removes that personal connection’s access and saved approvals. The user must connect again before using it.
* Successfully reconnecting replaces the saved credentials and clears remembered approvals. Starting or cancelling replacement authorization does not discard the existing credentials.

These settings belong to the signed user/account, so starting a new session does not reset them.

Forms must not collect passwords, access tokens, or payment credentials. Use an external connection page for those interactions. MCP form approval is separate from OAuth consent and from any approval policy you configure for actions.

## Related Documentation

<CardGroup>
  <Card title="Install Widget" icon="plug" href="/widget/install-widget">
    Load the widget with HTML, React, or headless setup.
  </Card>

  <Card title="Configuration" icon="gear" href="/widget/configuration">
    Prefill data, prompts, routing, and advanced widget behavior.
  </Card>

  <Card title="Conversation Sessions" icon="route" href="/widget/conversation-sessions">
    See how identity choices change history and continuity.
  </Card>

  <Card title="Mobile Support" icon="phone" href="/widget/native-mobile">
    Use verified contact tokens inside mobile WebViews.
  </Card>
</CardGroup>


# Widget v5 Companion mode
Source: https://docs.open.cx/widget/companion-mode

Bring Companion into your website with Widget v5. Configure floating layouts, page context, marked screenshots, mentions and available AI features.

Companion brings help into the page your visitor is already using. Open it from a small launcher, ask a question, and move between a floating workspace, sidebar and fullscreen as the task grows.

<Frame>
  <video aria-label="Widget v5 Companion: opening, streaming replies, page annotations and a scheduled follow-up" />
</Frame>

<Info>
  This guide describes **Widget 5.0.0**. Check [version availability](/widget/install-widget#choose-your-version) before installing. Companion controls layout; agent features also work in the classic popover when their delivery and permission requirements are met.
</Info>

## Add Companion to your site

Get your widget token from [Channels → Web chat](https://platform.open.cx/channels/configure/widget). For a React integration:

```bash theme={"dark"}
npm install @opencx/widget-react@5.0.0
```

Mount the widget once in your app's client-side layout:

```tsx theme={"dark"}
import { Widget } from "@opencx/widget-react";

export function SupportWidget() {
  return (
    <Widget
      options={{
        token: "<WIDGET_TOKEN>",
        displayMode: "companion",
        companion: {
          layouts: ["compact", "sidebar", "fullscreen"],
          defaultLayout: "compact",
        },
      }}
    />
  );
}
```

For an HTML site, follow [Install Widget](/widget/install-widget) and pass the same options directly to `initOpenScript`. Use one integration on a page. If you set `inline: true`, inline rendering takes precedence over Companion mode.

<Tip>
  [Install the integration skill](/widget/agent-skills), then ask your coding
  assistant: “Use opencx-widget-integration to add Widget v5 in Companion
  mode to this app. Exclude query strings, fragments and private path or title data from page context.”
</Tip>

## Choose the layouts visitors can use

| Option | What visitors see |
| - | - |
| `compact` | A floating workspace. The layout picker calls this **Floating**. |
| `sidebar` | A panel at the page edge. It floats over the page by default. |
| `fullscreen` | An expanded workspace with more room for longer replies. |

`companion.layouts` controls the choices and their order. Keep one layout to hide the picker. `defaultLayout` accepts `compact` or `sidebar`; when omitted, the first allowed layout is used. An empty layout list falls back to all three.

To place Companion beside your page instead of over it:

```tsx theme={"dark"}
<Widget
  options={{
    token: "<WIDGET_TOKEN>",
    displayMode: "companion",
    companion: {
      defaultLayout: "sidebar",
      layouts: ["sidebar", "fullscreen"],
      sidebar: { side: "auto", mode: "docked", width: 400 },
    },
  }}
/>
```

Docked mode reframes the host page to make space for the sidebar. Use `mode: 'floating'` when the page layout should stay unchanged. `side: 'auto'` uses the right edge on left-to-right pages and the left edge on right-to-left pages.

## Starter questions, bubbles and avatars

Starter questions appear in order above the Companion composer. Visitors can type instead unless you require a choice:

```tsx theme={"dark"}
const options = {
  token: '<WIDGET_TOKEN>',
  displayMode: 'companion',
  initialQuestions: ['Where is my order?', 'How do returns work?'],
  requireInitialQuestion: true,
  companion: { bubbles: false, avatars: true },
};
```

With `requireInitialQuestion: true`, the composer stays visible but disabled until a starter is selected. Selection sends the question and enables follow-ups. Resuming a session with messages does not require another choice. Empty question lists leave typing available. Set the option to `false` or omit it for optional starters.

`companion.bubbles` and `companion.avatars` are independent. Use either, both, or neither. If `avatars` is omitted, it follows `bubbles`. The popover keeps its chat bubbles and avatars.

## Enable the capabilities you need

Open [Channels → Web chat](https://platform.open.cx/channels/configure/widget) to copy your widget token and manage website features next to a live preview. Feature switches save as you change them; a successful save refreshes the preview. On smaller screens, use the **Settings** and **Preview** tabs.

**Try your widget** opens a simple demo landing page. Select **Try page actions** to open a small form with a name field, contact preference and updates checkbox. You can edit and save these preferences, or ask your agent to help when the corresponding page features are enabled for your organization. **Back to demo** returns to the landing page and keeps your changes; **Reload preview** resets them. Form changes affect only the demo; chat still uses your organization's agent. The form does not change contact or notification settings. The demo chats as you, with your dashboard name and email. Sessions you start there appear in your inbox under your name and stay in the demo history on that browser.

Under **Appearance**, use **Companion mode** to switch the demo between Companion and classic chat. It starts on and changes only the preview; your website's layout still follows its embed settings. Switching layouts keeps the demo's form values.

Use **Enter fullscreen** in the demo toolbar to fill the current page area without resetting the preview. The OpenCX sidebar stays available. Select **Exit fullscreen** or press **Escape** to return to settings.

If your organization has a website configured, **Open your website** opens it in a new tab. Install the widget there to test your actual pages, sign-in, cookie notices and navigation. The dashboard demo does not install the widget on your website.

| Web chat setting | What it enables |
| - | - |
| **Rich replies** | Supported cards and tables in streamed replies and saved history. |
| **Voice dictation** | Speaking into the message composer. |
| **File uploads** | Visitors sending files and images. On by default. |
| **Sees the page** | Page context, selected text, marked regions and mentions. |
| **Points at the page** | Letting the agent mark the control it is talking about. |
| **Acts on the page** | Letting the agent click, type and choose for the visitor. |
| **Asks to narrow a request** | Offering choices when a request needs clarification. |

Use **Advanced settings** at the bottom of the page, or open [Settings → Advanced](https://platform.open.cx/settings/ai-features), for capabilities used across channels:

* **Progress updates** lets the agent send short updates during longer tasks on web chat, WhatsApp, Instagram, Messenger, and Slack. These are separate messages and do not require streamed replies. Web chat still follows the organization and embed preferences, including when it uses polling. Updates are withheld in assist mode and when the reply must stay silent; they are not sent on SMS, email, voice, API, or app review channels. Connected messaging channels must be able to send a reply; WhatsApp's reply window still applies. If delivery fails or is cancelled, the update is recorded as an internal note with unconfirmed delivery rather than a customer reply.
* **Remembers past sessions** controls whether the agent can recall the contact's earlier sessions.
* **Team in the loop** lets the agent ask your team for help in Inbox without transferring: it leaves a note, mentions the team, tags the session **AI needs help**, and stays on the session. A teammate's reply in the note's thread answers the request and the agent continues with the answer; after a direct reply to the customer, the agent picks up on the customer's next message. The tag stays for historical filtering. To take over, open the **AI** assignee menu in the session header and choose **Take over**. Handoff keeps working exactly as configured, and your team must work in Inbox. See [Handoff settings](/handoff/settings#team-in-the-loop).
* **Scheduled follow-ups**, **Task plans**, **Workspace** and **Builds mini apps** are available on request. Enabled scheduled follow-ups let the agent check back and continue the same session later.
* Features available to your organization have a switch. Other features show **Contact us** to request access. Editing requires the appropriate settings permission.

Progress updates follow your AI profile and [training scenarios](/ai-instructions/training-scenarios). Within a session, new updates are written to avoid repeating the wording of updates the customer has already seen. To change how often updates appear, add a **Behavioral** scenario, for example: *Send a progress update only for a new request or a retry. Do not send one for follow-up questions, clarifications or extra details about something you just looked up; answer those directly.* Frequency rules are followed more consistently in a behavioral scenario than in the AI profile. Describe the length or tone you want in the same way, then review a few sessions after the change. A scenario-specific answer that scripts the reply, such as a link or fixed text, is sent without a progress update. To turn updates off for one website, add `preamble: false` to that embed's `features`.

Manage transfer to your team separately in [Handoff settings](https://platform.open.cx/settings/handoff).

To show final replies as they are written, set `streaming: true` and enable streaming for your organization. Selecting Companion or installing v5 does not turn it on. Omitted or `false` keeps polling, including with the v2 agent. `presentation.streaming: false` hides incremental text while keeping the streaming transport for supported interactions. If replies still arrive all at once, contact your OpenCX administrator or support team to check availability.

You can narrow supported features for one embed. For example, add `features: { dictation: false, clientTools: false }` to its options to hide dictation and prevent the agent from highlighting that page. In Widget 5.0.0, page access requires explicit embed opt-in: `pageContext: true` for reading, also `clientTools: true` for pointing, and also `pageActions: true` for acting. Omission keeps these page permissions off. Organization permission is also required.

Turn off **File uploads** if your team must not receive documents from visitors. The widget then hides the attach button, drag and drop, and paste, and messages with files are refused for every embed and custom client. Marked regions still send, without their screenshot. To hide uploads on one embed only, add `attachments: false` to its `features`; widget versions without this option ignore it.

## Opt into page assistance

For page reading, pointing and actions, enable the corresponding Web chat settings and use:

```tsx theme={"dark"}
const options = {
  token: '<WIDGET_TOKEN>',
  streaming: true,
  features: {
    pageContext: true,
    clientTools: true,
    pageActions: true,
  },
};
```

This works with the default popover or with `displayMode: 'companion'`. Enable only the permissions you intend: reading needs `pageContext`; pointing also needs `clientTools`; actions need all three. Each action asks the visitor to approve. A headless client also needs its own page-effect renderer and consent implementation before declaring support.

Generic forms and a customer-defined catalog of components for agent-generated rich replies are not part of the built-in rich-reply catalog. [Custom action-result components](/widget/custom-components-react) and [personal-connection forms](/widget/connections#review-tool-requests) are separate integrations.

## Share the current page

The opt-in defaults above require Widget 5.0.0. Earlier v5 beta embeds can inherit enabled organization settings for omitted flags. Until you upgrade, disable page access explicitly with `features: { pageContext: false, clientTools: false, pageActions: false }`; a server update alone does not change an older embed's defaults.

Host-supplied context is sent with messages, stored in the session history, and can be included in the agent’s input. Send only the page information the agent needs. The examples combine `window.location.origin` and `window.location.pathname`, so query parameters and URL fragments are excluded. Those values can contain login tokens, search terms or other private data and should not become part of the stored session. If your path or page title also contains private information, replace it with an approved route label or omit it.

Use a `context` function so each message includes the page at the time it is sent. You can also provide the record the visitor is viewing:

```tsx theme={"dark"}
<Widget
  options={{
    token: "<WIDGET_TOKEN>",
    displayMode: "companion",
    streaming: true,
    features: { pageContext: true },
    context: () => ({
      page: {
        url: window.location.origin + window.location.pathname,
        title: document.title,
      },
      entity: {
        type: "order",
        id: "order_123",
        title: "Order #123",
        meta: { status: "processing" },
      },
    }),
  }}
/>
```

Replace the example entity with the current record from your application. It appears as a removable context pill in the composer when page context is enabled. URL changes refresh the pill. If the selected record changes without navigation, notify the widget:

```js theme={"dark"}
window.dispatchEvent(new Event("opencx:context-changed"));
```

In an app that updates without reloading, have the callback read current state from a store or ref. Keep one mounted widget and update its options as the signed-in user or account changes.

<Note>
  Only supply context you intend the agent to receive. `features.pageContext:
      false` disables widget-collected page context and its controls; it does not
  remove the host application's `context` from messages. Remove or narrow that
  callback separately when needed.
</Note>

## What the agent reads from the page

With **Sees the page** and `features.pageContext: true` enabled, the widget also reads the controls a visitor can see — buttons, links, fields, tabs — and sends their names with each message, so the agent can answer "where do I turn that off" without the visitor hunting for the switch first.

The automatic control list includes names, roles, references and disabled state; it excludes input values. The widget skips private and sensitive controls, hidden controls, its own interface and controls it cannot name. This does not scrub data you deliberately supply in `context`, messages, uploaded files or action request fields. Review that data separately.

To keep part of a page out entirely, mark it private:

```html theme={"dark"}
<section data-opencx-private>
  <!-- Exclude this region from widget-collected page context. -->
</section>
```

Put the attribute on the outermost element of the region; everything inside it is excluded, at every depth.

<Note>
  The agent can only ever refer to a control the widget offered it for that
  message. A control inside a private region, or one the widget skipped, cannot
  be named, pointed at or used.
</Note>

## Let the agent act on the page

**Acts on the page** is off until you turn it on, and it is the only capability that changes something on a visitor's screen rather than describing it. With it on, the agent can click a control, type into a field, choose from a dropdown, or switch something on or off — always by pointing at a control the widget read for that message, never by a selector it wrote.

With Widget 5.0.0, before every action — including typing or changing a selection — the visitor sees the named control and proposed value and chooses Allow or No. A No is final for that request: the agent is told, and does not ask again or reach the same control another way.

What it will not do, whatever it is asked:

* Password fields and file pickers.
* Controls inside another site embedded in your page.
* Anything inside a region you marked `data-opencx-private`.
* Anything covered by a dialog or banner, or no longer on the page.

The agent receives the browser outcome and an updated list of controls. The new list replaces the previous screen, even when empty. If a control disappeared, the widget returns the current controls without clicking a replacement automatically.

In Widget 5.0.0, a control reused for another row or item requires a fresh page reading and approval. The widget checks changes to the control's name, native operation, and surrounding content. On pages without a clear item boundary, other content changes can also require a fresh reading. These checks cannot detect changes held only in your application's private state with no corresponding page change.

An interrupted action is not a confirmed completion, even when a hover, press, or focus handler already changed the page. It also does not prove that nothing happened. The agent must explain the uncertainty and ask the visitor to verify before trying again.

Widget 5.0.0 waits up to three seconds for visible regions marked `aria-busy="true"` to finish loading. A page without a loading signal can appear settled before a delayed request finishes. A timeout or visible change does not confirm that a payment, save, or other remote operation succeeded. The agent must report uncertainty and ask the visitor to verify before repeating an action.

Clicks run your site's normal event handlers. Test multi-step flows on your site, including loading states, navigation and auto-saving fields. Full page reloads can interrupt the live session response; the visitor may need to send an updated message after the page opens.

## Mark a region and attach a screenshot

With **Sees the page** enabled and `features.pageContext: true`:

1. Open the expanded Companion panel and choose **Mark something on the page to ask about it** in the composer.
2. Click the page element you want to discuss. Choose a shape such as **Box**, **Circle** or **Arrow**, and adjust the marked region.
3. Add a note such as “Explain this balance.” Press Enter or choose **Attach mark**.
4. Review the marked screenshot in the composer, add your question, and send. Remove the attachment first if you change your mind.

Press Escape to cancel marking. These controls appear in the expanded panel; set `companion.quickAskTools: 'all'` if you also want attachment and page-mark controls in the quick-ask bar.

## Let visitors mention records

Configure `mentions.items` for a fixed list, or `mentions.search` for records loaded as the visitor types. Each item needs `type`, `id` and `title`:

```tsx theme={"dark"}
<Widget
  options={{
    token: "<WIDGET_TOKEN>",
    displayMode: "companion",
    streaming: true,
    features: { pageContext: true },
    mentions: {
      items: [
        { type: "order", id: "order_123", title: "Order #123" },
        { type: "order", id: "order_124", title: "Order #124" },
      ],
    },
  }}
/>
```

Visitors type `@` and pick a record. The selected records travel with the message when page context is enabled. Supply only records the signed-in visitor is allowed to access; mentioning an ID does not grant access to it.

## Verify the experience

Open the launcher, switch layouts and send a message. With streaming enabled, confirm text arrives progressively and **Stop** interrupts the reply. A message sent during a reply can steer the current task or wait for it to finish.

Then navigate to a different page before sending, attach a marked screenshot, and reload to check session history. If scheduled follow-ups are enabled, ask for a check-in at a specific time and confirm the schedule the agent creates. Test human handoff as part of your normal support flow.

See the [configuration reference](/widget/configuration-reference#widget-v5-options) for more options and [Migrate to v5](/widget/migrate-to-v5) for existing integrations.


# Widget configuration
Source: https://docs.open.cx/widget/configuration

Customize the AI Chat Widget for your brand, launch behavior, visitor flow, prompts, session rules, and advanced website use cases.

Use this page when the widget is already installed and you want it to feel right for your website, support workflow, and visitor journey.

<Tip>
  Prefer tinkering to reading? The **[Playground](/widget/playground)** lets you tweak the most common options live and copy the generated snippet. Need implementation guidance for richer widget UI? Go straight to [Custom Components](/widget/custom-components), [React Components](/widget/custom-components-react), or [Headless](/widget/custom-components-headless).
</Tip>

## Configure Widget v5

For Widget v5, [Companion mode](/widget/companion-mode) covers the floating workspace, sidebar and fullscreen layouts, page context, annotations and mentions. Set `displayMode: 'companion'` in your widget options to use it; the classic popover remains the default.

Choose website capabilities in [Channels → Web chat](https://platform.open.cx/channels/configure/widget), alongside the live widget preview. Use [Settings → Advanced](https://platform.open.cx/settings/ai-features) for progress updates, memory and available capabilities such as scheduled follow-ups. The embed's `features` options can switch supported capabilities off for one site; setting them to `true` does not enable an organization-disabled feature. Installing v5 or a coding skill does not turn on streaming for your organization.

See the [v5 configuration reference](/widget/configuration-reference#widget-v5-options) for option names, or [install a coding skill](/widget/agent-skills) to help apply them in your app.

## Decide what to configure

<AccordionGroup>
  <Accordion title="How should the widget look?" icon="paintbrush">
    Decide on the widget brand, copy, colors, launcher visuals, and deeper styling.
  </Accordion>

  <Accordion title="How should the widget open?" icon="message">
    Decide between the default floating launcher, inline embed, open-by-default behavior, and delayed open.
  </Accordion>

  <Accordion title="What should visitors see first?" icon="comment">
    Decide what visitors should see first, including welcome copy, suggested questions, and a quick resolution prompt.
  </Accordion>

  <Accordion title="What extra data should travel with the conversation?" icon="database">
    Decide what AI context, human-only metadata, and action-request data should travel with the conversation.
  </Accordion>
</AccordionGroup>

## Match The Widget To Your Brand

<Tabs>
  <Tab title="Bot and human identity">
    <Steps>
      <Step title="Set the AI identity visitors should see">
        Use <Tooltip>`bot`</Tooltip> for the AI name and avatar shown in the widget header and AI messages.
      </Step>

      <Step title="Set the default human-support appearance">
        Use <Tooltip>`humanAgent`</Tooltip> when your team wants a consistent human avatar after handoff.
      </Step>

      <Step title="Apply both in one options object">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          bot: {
            name: 'Acme Support',
            avatarUrl: 'https://example.com/acme-bot.png',
          },
          humanAgent: {
            avatarUrl: 'https://example.com/support-team.png',
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Logos and launcher visuals">
    <Steps>
      <Step title="Decide what brand visuals should appear">
        Use <Tooltip>`assets`</Tooltip> when the widget should look like part of your site instead of a generic chat tool.
      </Step>

      <Step title="Start with the welcome logo">
        The most common first change is the organization logo on the welcome screen.
      </Step>

      <Step title="Add the assets object">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          assets: {
            organizationLogo: 'https://example.com/logo.png',
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Theme, language, and copy">
    <Steps>
      <Step title="Use theme for color and layout">
        <Tooltip>`theme`</Tooltip> controls colors, panel sizing, spacing, and other layout-level visuals.
      </Step>

      <Step title="Use text settings for wording">
        `textContent`, `language`, and <Tooltip>`translationOverrides`</Tooltip> help the widget match your product vocabulary.
      </Step>

      <Step title="Start with a small configuration first">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          language: 'en',
          theme: {
            primaryColor: '#0A0A0A',
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Note>
  If the built-in theme options are not enough, use <Tooltip>`cssOverrides`</Tooltip> for deeper styling. This is the right option when you need to target specific widget parts with custom CSS.
</Note>

## Choose How The Widget Opens

<AccordionGroup>
  <Accordion title="Floating launcher" icon="message">
    Keep chat available across the site without taking permanent page space. See [Floating launcher setup](/widget/install-widget#floating-launcher).
  </Accordion>

  <Accordion title="Inline embed" icon="rectangle-list">
    Place the widget inside a page section, such as a help page, pricing page, or account area. See [Inline embed setup](/widget/install-widget#inline-embed).
  </Accordion>

  <Accordion title="Open by default" icon="arrow-up-right-from-square">
    Open the widget on first render for cases like a webview or a dedicated support screen. See [Open by default setup](/widget/install-widget#open-by-default).
  </Accordion>

  <Accordion title="Open after a delay" icon="clock">
    Open the widget after time on page when you want a proactive nudge instead of an always-on interruption. See [Delayed open setup](/widget/install-widget#open-after-a-delay).
  </Accordion>
</AccordionGroup>

<Info>
  Need to change session behavior too? Use options like <Tooltip>`oneOpenSessionAllowed`</Tooltip>, <Tooltip>`router.goToChatIfNoSessions`</Tooltip>, <Tooltip>`router.chatScreenOnly`</Tooltip>, and <Tooltip>`headerButtons`</Tooltip>. For the user-facing effect of those settings, see [Conversation Sessions](/widget/conversation-sessions).
</Info>

## Shape The First-Visit Experience

<Tabs>
  <Tab title="Welcome messages">
    <Steps>
      <Step title="Choose the opening message style">
        Use <Tooltip>`initialMessages`</Tooltip> when you want a simple welcome message for a new chat.
      </Step>

      <Step title="Use advanced messages only when needed">
        Switch to <Tooltip>`advancedInitialMessages`</Tooltip> when some opening messages should stay visible in the conversation and others should disappear after the first reply.
      </Step>

      <Step title="Keep the opening copy focused">
        Use the welcome area to set expectations, not to explain every feature of your support flow.
      </Step>
    </Steps>

    ```tsx theme={"dark"}
    const options = {
      token: '<WIDGET_TOKEN>',
      initialMessages: ['Hi, how can I help today?'],
    };
    ```
  </Tab>

  <Tab title="Suggested questions">
    <Steps>
      <Step title="List the most common starting intents">
        Use <Tooltip>`initialQuestions`</Tooltip> for the first few things visitors usually ask.
      </Step>

      <Step title="Choose the position">
        Use <Tooltip>`initialQuestionsPosition`</Tooltip> to decide whether they appear above the input or closer to the welcome copy.
      </Step>

      <Step title="Keep the list short">
        Pick the questions that reduce hesitation and help visitors start quickly.
      </Step>

      <Step title="Require a choice before typing (optional)">
        Set [`requireInitialQuestion`](/widget/configuration-reference#requireinitialquestion) to `true` to require a choice before typing. The popover hides the message box; Companion keeps it visible but disabled below the starter pills. Selection sends the first message and enables follow-ups. Leave it off to allow free text from the start.
      </Step>
    </Steps>

    ```tsx theme={"dark"}
    const options = {
      token: '<WIDGET_TOKEN>',
      initialQuestions: ['Where is my order?', 'Can I change my plan?'],
      requireInitialQuestion: true,
    };
    ```

    Each new or reset session requires a choice. Existing sessions with messages stay editable. Add at least one non-empty question; if the list is empty or contains only whitespace, the message box stays available.

    <Note>
      `requireInitialQuestion` is available in Widget `4.0.63` and Widget `5.0.0`. Earlier v5 betas, including beta.10, do not support it. Try it under **First visit → Require an initial question** in the [Playground](/widget/playground).
    </Note>
  </Tab>

  <Tab title="Helpful prompt">
    <Steps>
      <Step title="Turn on the prompt">
        Use <Tooltip>thisWasHelpfulOrNot</Tooltip> when you want the widget to ask whether the latest AI answer solved the issue.
      </Step>

      <Step title="Use it after self-serve answers">
        This works best when the AI often resolves issues without a human handoff.
      </Step>

      <Step title="Keep the next step clear">
        Pair it with your handoff setup so visitors who still need help know what happens next.
      </Step>
    </Steps>

    ```tsx theme={"dark"}
    const options = {
      token: '<WIDGET_TOKEN>',
      thisWasHelpfulOrNot: {
        enabled: true,
      },
    };
    ```
  </Tab>
</Tabs>

<Info>
  Need to collect visitor details before chat starts? Use <Tooltip>`collectUserData`</Tooltip> for the built-in form, <Tooltip>`prefillUserData`</Tooltip> when your site already knows the visitor’s name or email, and <Tooltip>`extraDataCollectionFields`</Tooltip> only for the extra fields you truly need.
</Info>

## Attach Context Without Changing The AI Prompt

<Tabs>
  <Tab title="AI context">
    <Steps>
      <Step title="Use context for runtime information">
        Use <Tooltip>`context`</Tooltip> for page-level or runtime details the AI may need on each message.
      </Step>

      <Step title="Keep it focused on what changes the answer">
        This is the right place for an approved page URL, product ID, or current screen context. Exclude query strings and fragments; if the path contains private information, send an approved route label instead.
      </Step>

      <Step title="Add the context object">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          context: {
            page: {
              url: window.location.origin + window.location.pathname,
            },
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Human-only message data">
    <Steps>
      <Step title="Use messageCustomData for per-message notes">
        <Tooltip>`messageCustomData`</Tooltip> travels with each contact message but is intended for human use, not to guide the AI response.
      </Step>

      <Step title="Use it for operational metadata">
        Good examples include app version, platform, or support workflow metadata.
      </Step>

      <Step title="Add the message metadata">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          messageCustomData: {
            platform: 'WEB',
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Session-level notes">
    <Steps>
      <Step title="Use sessionCustomData when the session starts">
        <Tooltip>`sessionCustomData`</Tooltip> is attached when the session is created and is useful for human operators and filtering.
      </Step>

      <Step title="Keep it tied to the session itself">
        Good examples include visit IDs, plan tier, workspace ID, or a support-route label.
      </Step>

      <Step title="Add the session metadata">
        ```tsx theme={"dark"}
        const options = {
          token: '<WIDGET_TOKEN>',
          sessionCustomData: {
            visitId: 'visit_123',
          },
        };
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Pass Data To AI Actions

If your AI calls your APIs, the widget can send request data with those action calls:

* <Tooltip>`headers`</Tooltip>
* <Tooltip>`queryParams`</Tooltip>
* <Tooltip>`bodyProperties`</Tooltip>

Use these when the action request needs customer-specific or page-specific data. If your main problem is secure API credentials, see [General settings](https://platform.open.cx/settings).

## Advanced UI: Conversation Modes

<Tabs>
  <Tab title="Use modesComponents">
    Use <Tooltip>modesComponents</Tooltip> when the widget should temporarily switch from normal chat to a guided flow, such as onboarding, qualification, or structured data collection.

    <CardGroup>
      <Card title="Good fit" icon="check">
        Multi-step flows, guided forms, and canvas-style experiences.
      </Card>

      <Card title="What you control" icon="sliders">
        The UI shown during the active mode, the submit action, and the exit flow back to the conversation.
      </Card>
    </CardGroup>

    <Note>
      Choose this when the widget is driving a flow, not just rendering the result of one action.
    </Note>
  </Tab>

  <Tab title="Use custom components">
    Use custom components when the AI stays in a normal chat thread but one action result should render as richer UI.

    <CardGroup>
      <Card title="Good fit" icon="bolt">
        Order summaries, balance cards, booking confirmations, and status views.
      </Card>

      <Card title="Where to continue" icon="paintbrush" href="/widget/custom-components">
        Use the custom components guides for the React and headless implementations.
      </Card>
    </CardGroup>

    <Info>
      Choose this when you are rendering a result inside the conversation, not taking over the conversation flow.
    </Info>
  </Tab>
</Tabs>

## Where To Go Next

This page is for choosing the right configuration direction. Use the implementation guides next when you need details:

<CardGroup>
  <Card title="Custom Components" icon="paintbrush" href="/widget/custom-components">
    Decide when richer UI is worth the extra implementation work.
  </Card>

  <Card title="React Components" icon="react" href="/widget/custom-components-react">
    Register action-specific UI in the default React widget.
  </Card>

  <Card title="Headless" icon="code" href="/widget/custom-components-headless">
    Build fully custom rendering with the headless widget packages.
  </Card>

  <Card title="Mobile Support" icon="phone" href="/widget/native-mobile">
    Configure the widget for iOS, Android, and React Native support screens.
  </Card>
</CardGroup>


# Configuration reference
Source: https://docs.open.cx/widget/configuration-reference

Every option you can pass to the AI Chat Widget — token, branding, identity, chat behavior, context, AI action request data, and custom mode components.

This page lists every option you can pass to the widget. For *how* to combine these options into a brand, launch flow, or visitor experience, start with [Configuration](/widget/configuration).

<Tip>
  Want to try options live and copy a working snippet? Open the **[Playground](/widget/playground)**.
</Tip>

<Info>
  Defaults shown as `undefined` mean no value is supplied. Read each option’s behavior: some inherit organization settings, while streaming, personal connections and page permissions require explicit opt-in. Defaults shown as language-specific (e.g. for [`textContent`](#textcontent)) come from the active [`language`](#language) translation, not a single hard-coded string.
</Info>

## Initialization

#### `token`

<ResponseField name="" type="string">
  Your organization's widget token. Find it in [Channels → AI Chat Widget](https://platform.open.cx/channels/configure/widget). The widget will not load without it.
</ResponseField>

## Widget v5 options

These options require v5. See [Install Widget](/widget/install-widget) for version selection and [Companion mode](/widget/companion-mode) for complete examples.

#### `displayMode`

<ResponseField name="" type="'popover' | 'companion'">
  Choose the classic corner popover or the Companion launcher and workspace. Ignored when `inline` is `true`. This controls the layout. Streaming requires explicit embed opt-in and organization support, in either layout.
</ResponseField>

#### `companion`

<ResponseField name="" type="object">
  Options used with `displayMode: 'companion'`.

  | Property | Values / default | Purpose |
  | - | - | - |
  | `layouts` | `['compact', 'sidebar', 'fullscreen']` | Available layouts, in picker order. A single layout hides the picker; an empty list restores all three. |
  | `defaultLayout` | `compact` or `sidebar`; defaults to first allowed layout | Initial layout. An excluded value falls back to the first allowed layout. |
  | `sidebar.side` | `auto`, `left`, `right`; default `auto` | Edge used for the sidebar. Auto follows the page direction. |
  | `sidebar.mode` | `floating` or `docked`; default `floating` | Overlay the page or reframe it beside the sidebar. |
  | `sidebar.width` | `400` pixels | Sidebar width. |
  | `bubbles` | `false` | Use chat bubbles instead of flat replies. |
  | `avatars` | Follows `bubbles` | Show the sender's avatar beside each reply group, independently of bubble styling. Requires Widget `5.0.0-beta.10` or later. |
  | `icon` | Image URL | Replace the built-in launcher icon. |
  | `pillBackground` | Widget primary color | Launcher background. |
  | `placeholder` | Localized message placeholder | Quick-ask input copy. |
  | `pillLabel` | Falls back to `placeholder` | Text beside the resting launcher icon. |
  | `quickAskTools` | `history-only` or `all`; default `history-only` | Also show attachment and page-mark controls in the quick-ask bar. The expanded panel keeps its full tool row. |
  | `contentMaxWidth` | `48rem` | Fullscreen message-column width. |
  | `fullscreen.lockScroll` | `true` | Prevent host-page scrolling while fullscreen is open. |

  Set `companion: { bubbles: false, avatars: true }` to show avatars with flat replies. These controls apply to Companion; the popover always shows avatars.

  `compact` also accepts `maxWidth` (440), `minWidth` (280), `minHeight` (420), `maxHeight` (640), `viewportHeightRatio` (0.65) and `borderRadius` (20). Dimensions are pixels except the viewport-height ratio.
</ResponseField>

#### `features`

<ResponseField name="" type="object">
  Per-embed switches for `preamble`, `inlineUi`, `dictation`, `attachments`, `pageContext`, `clientTools` and `pageActions`. In Widget 5.0.0, `pageContext`, `clientTools` and `pageActions` each default to off and require explicit `true` as well as organization permission. Actions require all three and visitor approval. For the other switches, omission leaves the organization setting in charge. `false` always disables the capability in this embed; `true` cannot override an organization restriction.

  These defaults are enforced by the updated widget. Earlier v5 beta widgets can inherit enabled organization settings when a flag is omitted. Until you upgrade, use explicit `features: { pageContext: false, clientTools: false, pageActions: false }` to disable page access. Changing organization settings or updating the server alone does not give an older embed the new defaults.

  Manage web capabilities in [Channels → Web chat](https://platform.open.cx/channels/configure/widget) and progress updates in [Settings → Advanced](https://platform.open.cx/settings/ai-features). `attachments: false` hides file uploads in this embed; widget versions without this option ignore it. To refuse files for every embed and custom client, turn off **File uploads** in Web chat settings. Turning off `pageContext` does not remove host-supplied `context` from outgoing messages, but the new agent excludes that context and historical page selections from its prompt.
</ResponseField>

#### `streaming`

<ResponseField name="" type="boolean">
  Omitted or `false` uses polling for saved messages, preserving v4 delivery. Set `true` to opt into streamed replies when the organization supports them. Enabled progress updates can arrive on a poll before the final reply. Changing delivery does not change the agent version or require Companion. A runtime transport change waits for an accepted send and its reply to settle.
</ResponseField>

#### `streamingFetch`

<ResponseField name="" type="typeof fetch">
  The `fetch` used to send and resume streamed replies. Omitted uses the global `fetch`, which every other widget request uses. In React Native, pass the `fetch` from `expo/fetch`; see [Stream in React Native](/widget/custom-components-headless#stream-in-react-native). Available from Widget 5.1.0.
</ResponseField>

#### `presentation`

<ResponseField name="" type="object">
  Narrow what this embed shows. Organization limits in **Channels → Web chat → Reply display** apply to live replies, reconnects and history.

  | Property | Values | Behavior |
  | - | - | - |
  | `streaming` | boolean | Set `false` to show complete text while retaining the streaming transport for supported live interactions. |
  | `toolActivity` | `hidden`, `status`, `details` | Hide activity, show name/status only, or allow inputs and outputs. The organization default is `status`. |
  | `reasoning` | boolean | Set `false` to hide reasoning. The organization default is off. |

  An embed can show less than the organization allows, never more. Hiding activity does not stop tools from executing. Selectable questions and page highlights retain the data needed for their visible interaction. Polling can return saved progress updates and completed replies; it does not deliver live activity events.
</ResponseField>

#### `capabilities`

<ResponseField name="" type="object">
  Set `connections: true` to opt into personal connection controls and requests; omission or `false` keeps them off. Signed user/account access and streaming are also required for connection requests.

  Declare which interactions your client can render: `structuredQuestions`, `richReplies` and `pageEffects`. Enabling a capability does not enable the organization's feature.

  The standard widget declares its built-in support. A headless client must explicitly declare support after implementing the corresponding renderer or page-effect handler. Custom message or rich-reply renderers must declare their own support. Set an individual capability to `false` to opt out. Clients without support receive ordinary replies; the agent can still ask clarifying questions in text. The polling transport does not support these structured interactions.
</ResponseField>

<Info>
  This reference describes Widget 5.0.0. Earlier beta defaults differ; see [Migrate to v5](/widget/migrate-to-v5) before upgrading a beta integration.
</Info>

#### `mentions`

<ResponseField name="" type="object">
  Configure the `@` picker using either `items` (a fixed array) or `search` (a function returning an array or a promise of one). Use one source, not both.

  Each record needs `type`, `id` and `title`, with optional `description`, `icon`, `iconName` and `meta`. `preview` defaults to `true` and shows the selected item's description when the layout has room. Mentions require page context to be enabled. See [mention examples](/widget/companion-mode#let-visitors-mention-records).
</ResponseField>

## Branding

#### `assets`

<ResponseField name="" type="object">
  Brand visuals shown around the chat — organization logo and launcher icons.

  <Expandable title="properties">
    <ResponseField name="organizationLogo" type="string">
      Logo shown on the welcome screen.
    </ResponseField>

    <ResponseField name="widgetTrigger" type="object">
      <Expandable title="properties">
        <ResponseField name="openIcon" type="string">
          Icon shown on the launcher when the widget is closed.
        </ResponseField>

        <ResponseField name="closeIcon" type="string">
          Icon shown on the launcher when the widget is open.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

#### `bot`

<ResponseField name="" type="object">
  Identity of the AI shown in the widget header and AI message bubbles.

  <Expandable title="properties">
    <ResponseField name="name" type="string">
      Display name of the AI.
    </ResponseField>

    <ResponseField name="avatarUrl" type="string">
      Avatar image URL of the AI.
    </ResponseField>
  </Expandable>
</ResponseField>

#### `humanAgent`

<ResponseField name="" type="object">
  Default appearance applied to every human agent after <Tooltip href="/handoff/introduction">handoff</Tooltip>.

  <Expandable title="properties">
    <ResponseField name="avatarUrl" type="string">
      Default avatar image URL used for all human agents.
    </ResponseField>
  </Expandable>
</ResponseField>

#### `theme`

<ResponseField name="" type="object">
  Colors, panel sizing, spacing, and other layout-level visuals.

  <Expandable title="properties">
    <ResponseField name="palette" type="'neutral' | 'stone' | 'zinc' | 'slate'" />

    <ResponseField name="primaryColor" type="string" />

    <ResponseField name="widgetTrigger" type="object">
      Launcher button styling.

      <Expandable title="properties">
        <ResponseField name="zIndex" type="number" />

        <ResponseField name="offset" type="object">
          <Expandable title="properties">
            <ResponseField name="bottom" type="number (pixels)" />

            <ResponseField name="right" type="number (pixels)">
              Defaults to `20` when the host page is `ltr`, otherwise `initial`.
            </ResponseField>

            <ResponseField name="left" type="number (pixels)">
              Defaults to `20` when the host page is `rtl`, otherwise `initial`.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="size" type="object">
          <Expandable title="properties">
            <ResponseField name="button" type="number (pixels)" />

            <ResponseField name="icon" type="number (pixels)" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="widgetContentContainer" type="object">
      Outer container styling for the chat panel.

      <Expandable title="properties">
        <ResponseField name="borderRadius" type="string" />

        <ResponseField name="boxShadow" type="string" />

        <ResponseField name="outline" type="string" />

        <ResponseField name="outlineColor" type="string" />

        <ResponseField name="transitionProperty" type="string" />

        <ResponseField name="transitionTimingFunction" type="string" />

        <ResponseField name="transitionDuration" type="string" />

        <ResponseField name="zIndex" type="number" />

        <ResponseField name="offset" type="object">
          <Expandable title="properties">
            <ResponseField name="side" type="number (pixels)" />

            <ResponseField name="align" type="number (pixels)" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="screens" type="object">
      Per-screen sizing for the welcome, sessions, and chat panels.

      <Expandable title="properties">
        <ResponseField name="welcome" type="object">
          <Expandable title="properties">
            <ResponseField name="width" type="string" />

            <ResponseField name="minHeight" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="sessions" type="object">
          <Expandable title="properties">
            <ResponseField name="width" type="string" />

            <ResponseField name="height" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="chat" type="object">
          <Expandable title="properties">
            <ResponseField name="width" type="string" />

            <ResponseField name="height" type="string" />

            <ResponseField name="withCanvas" type="object">
              Sizing applied while the canvas is open (used by [`modesComponents`](#modescomponents)).

              <Expandable title="properties">
                <ResponseField name="width" type="string" />

                <ResponseField name="height" type="string" />

                <ResponseField name="transitionTimingFunction" type="string" />

                <ResponseField name="transitionDuration" type="string" />
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

#### `cssOverrides`

<ResponseField name="" type="string">
  Custom stylesheet that targets widget parts via `data-component` selectors. Use when the [`theme`](#theme) options are not enough.

  Inspect the DOM to find selectors like `data-component="chat/input_box/root"`. If a part you need to style does not yet have a selector, contact us and we will add one.

  <Expandable title="available selectors">
    ```ts theme={"dark"}
    export type OpenCxComponentNameU =
      | 'ui_lib/btn'
      | 'trigger/btn'

      /* Sessions screen */
      | 'sessions/root'
      | 'sessions/header'
      | 'sessions/new_conversation_btn'

      /* Chat screen */
      | 'chat/root'
      | 'chat/header'
      | 'chat/main/root'
      | 'chat/canvas/root'
      | 'chat/msgs/root'

      /* Agent message */
      | 'chat/agent_msg_group/root'
      | 'chat/agent_msg_group/avatar_and_msgs/root'
      | 'chat/agent_msg_group/avatar_and_msgs/avatar'
      | 'chat/agent_msg_group/avatar_and_msgs/msgs'
      | 'chat/agent_msg_group/root/avatar'
      | 'chat/agent_msg_group/suggestions'
      | 'chat/agent_msg/root'
      | 'chat/agent_msg/msg'

      /* User message */
      | 'chat/user_msg_group/root'
      | 'chat/user_msg_group/avatar/root'
      | 'chat/user_msg/root'
      | 'chat/user_msg/msg'

      /* Chat input */
      | 'chat/input_box/root'
      | 'chat/input_box/inner_root'
      | 'chat/input_box/textarea_and_attachments_container'
      | 'chat/input_box/textarea'
      | 'chat/input_box/attachments_container'

      /* Chat utilities */
      | 'chat/bot_loading/root'
      | 'chat/bot_loading/bouncing_dots_container'
      | 'chat/suggested_reply_btn'
      | 'chat/might_solve_user_issue_suggested_replies_container';
    ```
  </Expandable>

  <Expandable title="example">
    ```ts theme={"dark"}
    {
      cssOverrides: `
        * {
          font-family: "Arial", sans-serif;
        }

        [data-component="ui_lib/btn"][data-variant="ghost"]:hover {
          background: rgba(68, 71, 70, 0.08);
        }

        [data-component="chat/agent_msg_group/root/avatar"] {
          border-width: 2px;
          border-color: white;
          display: initial;
        }
        [data-component="chat/agent_msg_group/avatar_and_msgs/avatar"] {
          display: none;
        }
        [data-component="chat/agent_msg_group/suggestions"] {
          padding-left: unset;
        }
      `,
    }
    ```
  </Expandable>
</ResponseField>

#### `language`

<ResponseField name="" type="string">
  Language code used for built-in widget copy.

  Supported codes:

  * `ar` Arabic
  * `da` Danish
  * `de` German
  * `en` English
  * `es` Spanish
  * `fi` Finnish
  * `fr` French
  * `it` Italian
  * `nl` Dutch
  * `no` Norwegian
  * `pl` Polish
  * `pt` Portuguese
  * `ro` Romanian
  * `sv` Swedish
  * `tr` Turkish

  <Info>
    Need another language? Contact support or open a [pull request](https://github.com/openchatai/widget).
  </Info>
</ResponseField>

#### `textContent`

<ResponseField name="" type="object">
  Override built-in copy on individual screens. Defaults come from the active [`language`](#language).

  <Expandable title="properties">
    <ResponseField name="welcomeScreen" type="object">
      <Expandable title="properties">
        <ResponseField name="title" type="string" />

        <ResponseField name="description" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="sessionsScreen" type="object">
      <Expandable title="properties">
        <ResponseField name="headerTitle" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="chatScreen" type="object">
      <Expandable title="properties">
        <ResponseField name="headerTitle" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

#### `translationOverrides`

<ResponseField name="" type="{ [key in Language]?: Partial<TranslationInterface> }">
  Override individual translation strings per language. See [`language`](#language) for the list of supported codes.

  <Expandable title="TranslationInterface">
    ```ts theme={"dark"}
    export type TranslationInterface = {
      i_need_more_help: string;
      this_was_helpful: string;
      write_a_message_placeholder: string;
      your_issue_has_been_resolved: string;
      new_conversation: string;
      back_to_conversations: string;
      closed_conversations: string;
      no_conversations_yet: string;
      welcome_screen_title: string;
      welcome_screen_description: string;
      your_name_placeholder: string;
      your_email_placeholder: string;
      optional: string;
      start_chat_button: string;
      start_chat_button_loading: string;
    };
    ```
  </Expandable>

  <Expandable title="example">
    ```ts theme={"dark"}
    {
      translationOverrides: {
        en: {
          i_need_more_help: `This didn't answer my question`,
          this_was_helpful: `It's all good!`,
        },
        ar: {
          start_chat_button: 'يلا ندردش',
        },
      },
    }
    ```
  </Expandable>
</ResponseField>

#### `timestamps`

<ResponseField name="" type="object">
  Display timestamps in the conversation.

  <Expandable title="properties">
    <ResponseField name="perMessageGroup" type="object">
      <Expandable title="properties">
        <ResponseField name="enabled" type="boolean">
          Show a timestamp at the top of each message group.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

#### `disableTooltips`

<ResponseField name="" type="boolean">
  Disable the in-widget hover tooltips on UI controls (e.g. header buttons). Has no effect on documentation tooltips.
</ResponseField>

#### `inline`

<ResponseField name="" type="boolean">
  Embed the widget inside its parent element instead of floating over the page.

  When `true`, the widget content fills its parent container, the widget stays open, and the launcher button is hidden. Useful when you want a chat panel built into a page section.
</ResponseField>

#### `headerButtons`

<ResponseField name="" type="{ sessionsScreen?: Array<HeaderButton>; chatScreen?: Array<HeaderButton> }">
  Custom header buttons for the sessions and chat screens — expand-shrink the widget, close it, resolve the session, and so on.

  <Warning>
    Setting this option removes the default `close-widget` button on small screens. Add a `close-widget` entry yourself if you still need one.
  </Warning>

  <Expandable title="HeaderButton">
    ```ts theme={"dark"}
    type IconNameU =
      | 'Maximize'
      | 'Maximize2'
      | 'Minimize'
      | 'Minimize2'
      | 'Expand'
      | 'Shrink'
      | 'X'
      | 'SquareX'
      | 'CircleX'
      | 'Check'
      | 'CheckCheck'
      | 'CircleCheck'
      | 'CircleCheckBig'
      | 'SquareCheck'
      | 'SquareCheckBig';

    type HeaderButtonBase = {
      icon?: IconNameU;
      hideOnSmallScreen?: boolean;
      hideOnLargeScreen?: boolean;
    };

    type HeaderButton =
      | (HeaderButtonBase & {
          functionality: 'expand-shrink';
          /** Overridden by HeaderButtonBase.icon if set. */
          expandIcon?: IconNameU;
          /** Overridden by HeaderButtonBase.icon if set. */
          shrinkIcon?: IconNameU;
        })
      | (HeaderButtonBase & {
          functionality: 'close-widget';
          /**
           * Side effect run on click. Overrides the default close behavior —
           * useful when the widget's open/closed state is controlled externally.
           */
          handleClick?: () => void;
        })
      | (HeaderButtonBase & {
          functionality: 'resolve-session';
          /** What happens after the session is resolved. @default 'stay-in-chat' */
          onResolved?:
            | 'stay-in-chat'
            | 'reset-chat'
            | 'close-widget'
            | 'reset-chat-and-close-widget';
          /** Optional confirmation dialog before resolving. */
          confirmation?: {
            type: 'modal';
            title?: string;
            description?: string;
            confirmButtonText?: string;
            cancelButtonText?: string;
          };
          /** Behavior before the session is created. @default 'disabled' */
          behaviorBeforeSessionCreation?: 'disabled' | 'close-widget';
          /** Behavior after the session is resolved. @default 'disabled' */
          behaviorIfSessionIsResolved?:
            | 'disabled'
            | 'reset-chat'
            | 'close-widget'
            | 'reset-chat-and-close-widget';
        });
    ```
  </Expandable>

  <Expandable title="expand-shrink example">
    ```ts theme={"dark"}
    {
      headerButtons: {
        sessionsScreen: [
          {
            functionality: 'expand-shrink',
            expandIcon: 'Expand',
            shrinkIcon: 'Shrink',
          },
        ],
        chatScreen: [
          {
            functionality: 'expand-shrink',
            expandIcon: 'Expand',
            shrinkIcon: 'Shrink',
          },
        ],
      },
    }
    ```
  </Expandable>

  <Expandable title="resolve-session example">
    ```ts theme={"dark"}
    {
      headerButtons: {
        chatScreen: [
          {
            functionality: 'resolve-session',
            icon: 'X',
            behaviorBeforeSessionCreation: 'close-widget',
            behaviorIfSessionIsResolved: 'reset-chat-and-close-widget',
            confirmation: {
              type: 'modal',
              title: 'Close conversation',
              description: 'Are you sure you want to close this conversation?',
              confirmButtonText: 'Yes',
              cancelButtonText: 'No',
            },
          },
        ],
      },
    }
    ```
  </Expandable>

  <Expandable title="close-widget example">
    ```ts theme={"dark"}
    {
      headerButtons: {
        sessionsScreen: [
          {
            functionality: 'close-widget',
            icon: 'CircleX',
          },
        ],
        chatScreen: [
          {
            functionality: 'close-widget',
            icon: 'CircleX',
          },
        ],
      },
    }
    ```
  </Expandable>
</ResponseField>

## User

#### `collectUserData`

<ResponseField name="" type="boolean">
  Show a built-in form on the welcome screen that asks for the visitor's name and email. The submitted values create a non-verified <Tooltip>contact</Tooltip>.

  Use [`prefillUserData`](#prefilluserdata) and [`extraDataCollectionFields`](#extradatacollectionfields) to tailor the form. For verified identity, see [Authentication](/widget/authentication).
</ResponseField>

#### `prefillUserData`

<ResponseField name="" type="object">
  Initial values for the `name` and `email` inputs in the welcome screen. Requires [`collectUserData`](#collectuserdata) to be `true`.

  <Expandable title="properties">
    <ResponseField name="name" type="string" />

    <ResponseField name="email" type="string" />
  </Expandable>
</ResponseField>

#### `extraDataCollectionFields`

<ResponseField name="" type="Array<string>">
  Extra free-text fields to add to the welcome form, beyond `name` and `email`. Requires [`collectUserData`](#collectuserdata) to be `true`.
</ResponseField>

#### `user`

<ResponseField name="" type="object">
  Verified or non-verified contact data passed from your app. If omitted, an anonymous contact is used.

  See [Authentication](/widget/authentication) for the full setup, including how to mint a verified token from your backend.

  <Expandable title="verified contact properties">
    <ResponseField name="token" type="string">
      Server-issued contact token. Generate it via the [authenticate-contact API](/api-reference/widget/authenticate-contact).
    </ResponseField>

    <ResponseField name="externalId" type="string">
      Optional ID that scopes the contact's sessions per workspace — use it when one email can belong to multiple accounts in your application.
    </ResponseField>
  </Expandable>

  <Expandable title="non-verified contact properties">
    <ResponseField name="data" type="object">
      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Stored as `non_verified_name`. Will not override the name on a verified contact with the same email.
        </ResponseField>

        <ResponseField name="email" type="string" />

        <ResponseField name="avatarUrl" type="string" />

        <ResponseField name="customData" type="Record<string, string | number | boolean>">
          Arbitrary user attributes. Stored as `non_verified_custom_data`.

          <Expandable title="example">
            ```ts theme={"dark"}
            {
              org_id: 'org_185938572649',
              vip: true,
              loyalty_points: 1200,
            }
            ```
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="externalId" type="string">
      Optional ID that scopes the contact's sessions per workspace.
    </ResponseField>
  </Expandable>
</ResponseField>

## Chat

#### `initialMessages`

<ResponseField name="" type="Array<string>">
  Messages the visitor sees in a new chat session. They disappear after the visitor sends their first message.
</ResponseField>

#### `advancedInitialMessages`

<ResponseField name="" type="Array<{ message: string; persistent?: boolean }>">
  Same idea as [`initialMessages`](#initialmessages) with per-message persistence control. When set, this overrides `initialMessages`.

  When `persistent` is `true`, the message stays pinned at the top of the chat; otherwise it disappears after the first reply.

  <Expandable title="example">
    ```ts theme={"dark"}
    {
      advancedInitialMessages: [
        { message: 'Hello, how can I help you?', persistent: true },
        { message: 'Please select an option from the list below:', persistent: false },
      ],
    }
    ```
  </Expandable>
</ResponseField>

#### `initialQuestions`

<ResponseField name="" type="Array<string>">
  Suggested starting questions shown at the top of a new chat. Clicking one sends it as the visitor's first message.

  To require a selection before visitors can type, enable [`requireInitialQuestion`](#requireinitialquestion).
</ResponseField>

#### `requireInitialQuestion`

<ResponseField name="" type="boolean">
  Require a visitor to select an [`initialQuestions`](#initialquestions) option before typing in a new session. In the popover, the message box is hidden until selection. In Companion, starter pills appear above the composer and the composer stays visible but disabled. Selecting a question sends it as the first message and enables follow-ups.

  Each new or reset session requires another selection. Resuming a session with messages keeps the message box available. If there are no initial questions, or all questions are empty or whitespace-only, the message box stays available.

  The popover supports both [`initialQuestionsPosition`](#initialquestionsposition) values. Companion places starter pills above its composer. Leave this option off to let visitors type their first message freely.

  Available in Widget `4.0.63` and Widget `5.0.0`. Earlier v5 betas, including beta.10, do not include this behavior.

  <Expandable title="example">
    ```ts theme={"dark"}
    {
      initialQuestions: ['Where is my order?', 'I need help with a return'],
      requireInitialQuestion: true,
      initialQuestionsPosition: 'below-initial-messages',
    }
    ```
  </Expandable>
</ResponseField>

#### `initialQuestionsPosition`

<ResponseField name="" type="'above-chat-input' | 'below-initial-messages'">
  Where the suggested questions appear relative to the chat input.
</ResponseField>

#### `thisWasHelpfulOrNot`

<ResponseField name="" type="object">
  Prompt the visitor to confirm whether the latest AI reply solved their issue. Renders as two buttons: "This was helpful" and "I need more help", after an AI reply that might have solved the issue.

  <Expandable title="properties">
    <ResponseField name="enabled" type="boolean" />
  </Expandable>
</ResponseField>

## Behavior

#### `isOpen`

<ResponseField name="" type="boolean">
  Whether the widget is open. Use to open the widget on first render (e.g. inside a webview) or to control its open state from your app.
</ResponseField>

#### `openAfterNSeconds`

<ResponseField name="" type="number">
  Open the widget automatically after N seconds on the page.
</ResponseField>

#### `oneOpenSessionAllowed`

<ResponseField name="" type="boolean">
  When `true`, the **New conversation** button is hidden while an open session already exists. See [Conversation Sessions](/widget/conversation-sessions) for the user-facing effect.
</ResponseField>

#### `router`

<ResponseField name="" type="object">
  Override the default screen routing.

  <Expandable title="properties">
    <ResponseField name="goToChatIfNoSessions" type="boolean">
      Navigate first-time visitors directly to the chat screen instead of the sessions list.
    </ResponseField>

    <ResponseField name="restoreLastSession" type="boolean">
      Reopen the last selected session when it is still open. The standard widget uses browser storage; a headless provider needs a storage adapter to persist the selection across reloads. Closing the session or starting a new one clears the saved active-session pointer.
    </ResponseField>

    <ResponseField name="chatScreenOnly" type="boolean">
      Show only the welcome and chat screens. The most recent open session is selected; if none exists, an empty conversation is opened and a session is created when the visitor sends a message. The "back to sessions" button is hidden.
    </ResponseField>
  </Expandable>
</ResponseField>

#### `anchorTarget`

<ResponseField name="" type="'_top' | '_blank'">
  Target attribute applied to all links rendered in AI or human-agent replies.

  * `_top` — open links in the same tab.
  * `_blank` — open links in a new tab.
</ResponseField>

#### `disableSendingWhenAwaitingAIReply`

<ResponseField name="" type="boolean">
  By default the send button is disabled while the AI is generating a reply. Set to `false` to let the visitor send another message before the AI finishes — the typing indicator stays visible; only the send button's disabled state is dropped.
</ResponseField>

## Context & custom data

#### `context`

<ResponseField name="" type="object | (() => object)">
  Runtime data sent with each visitor message so the AI can tailor its response. In v5, pass a function to read current state on each send. The `page` key accepts `url` and optional `title`; `entity` accepts `type`, `id`, `title` and optional `meta` and can appear as a context pill.

  Exclude query strings and fragments from page URLs. If a path or title contains private information, use an approved route label or omit it.

  For record changes without navigation, dispatch `opencx:context-changed` to refresh the pill. Have the callback read a ref or store so it reflects the record visible when the visitor sends. Host context is still sent when `features.pageContext` is `false`. See [page context guidance](/widget/companion-mode#share-the-current-page).

  <Expandable title="example">
    ```ts theme={"dark"}
    {
      context: {
        page: { url: window.location.origin + window.location.pathname },
        product_id: '99836009',
        product_name: 'Ineffective painkiller',
        product_price: 12.99,
      },
    }
    ```
  </Expandable>
</ResponseField>

#### `messageCustomData`

<ResponseField name="" type="object">
  Per-message metadata attached to each visitor message. Intended for human agents — the AI does not see it and it does not influence replies.

  <Expandable title="example">
    ```ts theme={"dark"}
    {
      messageCustomData: {
        platform: 'MOBILE',
        version: '1.3.57',
      },
    }
    ```
  </Expandable>
</ResponseField>

#### `sessionCustomData`

<ResponseField name="" type="Record<string, string | number | boolean>">
  Metadata attached to the session when it is created. Intended for human agents and for filtering sessions in the inbox — the AI does not see it.

  <Expandable title="example">
    ```ts theme={"dark"}
    {
      sessionCustomData: {
        visit_id: '0199e212-d7fd-71d3-808b-48d860bfa469',
      },
    }
    ```
  </Expandable>

  <Note>
    Keys prefixed with `opencx__` are reserved for OpenCX-specific controls. Set
    `opencx__ai_agent_version` to `'v2'` to upgrade that session to the latest AI
    agent. A session can only upgrade, never downgrade, so a lower value has no
    effect. The value is stored as session data, so you can also filter on it in the
    inbox. Omitting it uses the version from your channel settings.

    ```ts theme={"dark"}
    {
      sessionCustomData: {
        opencx__ai_agent_version: 'v2',
      },
    }
    ```
  </Note>
</ResponseField>

## AI action requests

These options attach data to every HTTP request the widget makes when the AI calls one of your APIs. For secure credentials, configure them in [General settings](https://platform.open.cx/settings) instead.

#### `headers`

<ResponseField name="" type="Record<string, string>">
  Custom headers added to every AI action request.

  <Expandable title="example">
    ```ts theme={"dark"}
    {
      headers: {
        auth_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
      },
    }
    ```
  </Expandable>
</ResponseField>

#### `queryParams`

<ResponseField name="" type="Record<string, string>">
  Custom query parameters appended to every AI action request URL.

  <Expandable title="example">
    ```ts theme={"dark"}
    {
      queryParams: {
        session_id: '9de647ba-25b9-4d9e-b51a-7ab2f4c68d9d',
      },
    }
    ```
  </Expandable>
</ResponseField>

#### `bodyProperties`

<ResponseField name="" type="Record<string, string>">
  Custom properties merged into the body of every AI action request.

  <Expandable title="example">
    ```ts theme={"dark"}
    {
      bodyProperties: {
        preferred_language: 'en',
      },
    }
    ```
  </Expandable>
</ResponseField>

## Components

#### `modesComponents`

<ResponseField name="" type="Array<ModeComponent>">
  Custom React components rendered in the canvas while a <Tooltip>mode</Tooltip> is active. See [Custom Components](/widget/custom-components) for the surrounding implementation guidance.

  <Expandable title="ModeComponent">
    <ResponseField name="key" type="string">
      The mode's ID, name, or slug.
    </ResponseField>

    <ResponseField name="component" type="(props: ModeComponentProps) => ReturnType<typeof React.createElement>">
      The functional component to render.
    </ResponseField>
  </Expandable>

  <Expandable title="ModeComponentProps">
    <ResponseField name="react" type="React">
      The React instance powering the widget. Use this instead of importing your own to avoid version mismatches.
    </ResponseField>

    <ResponseField name="mode" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="string" />

        <ResponseField name="name" type="string" />

        <ResponseField name="slug" type="string | null" />
      </Expandable>
    </ResponseField>

    <ResponseField name="createStateCheckpoint" type="(payload: Record<string, unknown>) => { success: boolean }">
      Persist state for whatever is happening inside the mode's component.
    </ResponseField>

    <ResponseField name="sendMessage" type="(payload: { content: string; exitModePrompt: string }) => void">
      Call at the end of the mode to submit a summary message and exit the mode.
    </ResponseField>

    <ResponseField name="isSendingMessage" type="boolean">
      Whether `sendMessage` is currently processing. Use to disable the submit button or show a loading indicator after submission.
    </ResponseField>
  </Expandable>

  <Expandable title="example">
    ```tsx theme={"dark"}
    function Onboarding(props: ModeComponentProps) {
      const [monthlyVolume, setMonthlyVolume] = props.react.useState(0);
      const [targetMarket, setTargetMarket] = props.react.useState('');

      const handleSubmit = async () => {
        // Submit to your system here, then end the mode with a summary
        // message and an exit prompt for the AI.
        props.sendMessage({
          content: `My expected volume is ${monthlyVolume} per month.\nMy target market is ${targetMarket}`,
          exitModePrompt: `
            Tell the user something like this:
            "Great! I've now submitted your request.
            We are already checking whether you are eligible to join our service.
            We will notify you as soon as we review your request.
            You can always check the progress by looking at the notifications on the top right of your dashboard."
          `,
        });
      };

      return props.react.createElement(
        'div',
        null,
        props.react.createElement('input', {
          value: monthlyVolume,
          onChange: (e) => setMonthlyVolume(Number(e.target.value)),
        }),
        props.react.createElement('input', {
          value: targetMarket,
          onChange: (e) => setTargetMarket(e.target.value),
        }),
        props.react.createElement(
          'button',
          {
            onClick: handleSubmit,
            disabled: !monthlyVolume || !targetMarket || props.isSendingMessage,
          },
          'Submit',
        ),
      );
    }

    const options = {
      token: '<WIDGET_TOKEN>',
      modesComponents: [
        {
          key: 'onboarding',
          component: Onboarding,
        },
      ],
    };
    ```
  </Expandable>
</ResponseField>

## Accessibility

#### `accessibility`

<ResponseField name="" type="object">
  Accessibility options for the widget UI.

  <Expandable title="properties">
    <ResponseField name="widgetTriggerButton" type="object">
      <Expandable title="properties">
        <ResponseField name="label" type="string">
          Accessible name for the launcher button. Applied as both `aria-label` (for assistive technology) and `title` (native hover tooltip).

          Required because the trigger is icon-only — satisfies WCAG 2.4.4 (Link Purpose) and 4.1.2 (Name, Role, Value).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  <Expandable title="example">
    ```ts theme={"dark"}
    {
      accessibility: {
        widgetTriggerButton: {
          label: 'Open support chat',
        },
      },
    }
    ```
  </Expandable>
</ResponseField>

***

## Related Documentation

<CardGroup>
  <Card title="Configuration" icon="gear" href="/widget/configuration">
    Job-first guidance — pick the right options for branding, launch flow, and visitor experience.
  </Card>

  <Card title="Playground" icon="flask" href="/widget/playground">
    Try options live and copy a working snippet.
  </Card>

  <Card title="Authentication" icon="shield-check" href="/widget/authentication">
    Identify signed-in visitors and protect conversation history.
  </Card>

  <Card title="Custom Components" icon="paintbrush" href="/widget/custom-components">
    Render richer UI for AI action results and conversation modes.
  </Card>
</CardGroup>


# Widget connections and approvals
Source: https://docs.open.cx/widget/connections

Let signed-in customers connect their own accounts in your widget. Set up services, scope account access, and manage saved approvals from one guide.

Let each customer use their own connected accounts while your team chooses the services and tools available from **[Actions](https://platform.open.cx/actions)**. Customers connect and review requests inside the widget; they do not need an OpenCX dashboard account.

<Info>
  Use Widget v5 and authenticate customers through your backend. Anonymous visitors and an unsigned email or `externalId` cannot authorize a personal connection. See [Install Widget](/widget/install-widget) and [Widget authentication](/widget/authentication#connect-each-customers-account).
</Info>

## Set up personal connections

<Steps>
  <Step title="Add the service in Actions">
    Add an MCP server and choose **Each user — their own account**. Enable the server and choose which tools your agent may use. Choose **Our team — one shared account** when everyone should use a connection your team manages instead.

    Fill in **Capabilities** with the actions the service supports, such as creating orders or tracking shipments. The agent uses this description to recognize when a request needs a connection, even when the service hides its tools until the customer authorizes access. Keep it current when you change the service or disable tools; do not include credentials or customer data. The description does not grant access: after authorization, the agent checks the tools available to that customer.

    Connection ownership is fixed when you create the server. See [MCP servers](/actions/mcp-servers) for supported authentication and tool controls.
  </Step>

  <Step title="Authenticate the customer from your backend">
    Resolve the customer from your application's signed-in session, call the widget authentication endpoint, and pass its result as `user.token`. Keep the organization API key on your server.

    Include `mcp_access: {}` in the backend authentication request to enable all personal servers in your organization. Omitting `mcp_access` keeps chat-only authentication. Optionally set `mcp_access.server_ids` to restrict that customer to a list; an empty list allows none. Include `mcp_access.account_id` when customers can switch accounts or workspaces.

    Follow the [authentication example and token renewal guidance](/widget/authentication#connect-each-customers-account).
  </Step>

  <Step title="Opt the embed into connection requests">
    Set `streaming: true` and `capabilities: { connections: true }`, and ensure your organization supports streaming. Both connection UI and requests are off when the capability is omitted. A token with `mcp_access` grants the permitted scope; it does not turn on the embed UI.

    ```tsx theme={"dark"}
    const options = {
      token: '<WIDGET_TOKEN>',
      user: { token: '<AUTHENTICATED_CONTACT_TOKEN>' },
      streaming: true,
      capabilities: { connections: true },
    };
    ```

    This works in the popover and Companion layouts. A headless client must supply the connection UI before declaring support.
  </Step>

  <Step title="Let the customer connect when needed">
    When a request needs account access, the widget shows **Connect**. The customer completes the service's authorization flow, returns to the widget, and the request continues after access is confirmed.

    Saved connections belong to the signed-in customer and account. Starting a new session keeps those connections. Pending prompts stay with their original session until answered, cancelled, or expired; they do not carry into the new session.
  </Step>
</Steps>

## Review tool requests

A connected service can request a form or a simple approval. The widget shows that request, sends the customer's answer back to the waiting tool, and lets it continue.

* **Approve once** accepts the current simple approval request.
* **Always allow** remembers approval only for the same connected account, server, tool, inputs, and form. Changed requests still ask.
* **Decline** rejects the request. **Cancel** closes it without accepting.
* Other forms require the customer to review and submit their answers each time.

Connecting an account and approving a tool request are separate decisions. A remembered approval does not override the service's access checks or your configured action permissions. See [form requests](/widget/authentication#mcp-form-requests) for supported fields, validation, and expiry.

## Manage connections and saved approvals

From the widget session list, open **Connections** and select a service. Only personal connections for the signed-in customer and account appear here; your team's shared connections stay in Actions.

| Action | Result |
| - | - |
| **Saved approvals → Remove approval** | Remove one remembered approval. The next matching request asks again; the account stays connected. |
| **Disconnect** | Remove the personal connection and its saved approvals. The customer must connect again to use it. |
| Connect again successfully | Replace the saved credentials and clear remembered approvals. Starting or cancelling replacement authorization keeps the existing connection. |

These settings stay with the customer and account across sessions.

## Use a connection from your backend

If your backend also needs the customer's connected account, enable **Reuse connections in your backend** on that personal server. This is off by default. Your backend can receive a connection-ready notification and retrieve the current access token with a separately scoped API key.

Follow [Reuse a customer connection in your backend](/widget/authentication#reuse-a-customer-connection-in-your-backend) for webhook verification, customer/account matching, and token retrieval. Use each token only with the service and permissions it was issued for.

If your backend already owns the downstream credentials, configure your authenticated gateway as the server instead. Your gateway handles its setup flow and verifies access when the widget retries; returning from a setup page alone does not prove the customer is connected.


# Conversation Sessions
Source: https://docs.open.cx/widget/conversation-sessions

Understand how the AI Chat Widget handles conversation history, returning visitors, handoff, resolution, and session continuity.

Use this page when you need to answer questions like: "Will visitors see old chats?", "What happens after handoff?", or "Why does history behave differently for anonymous and signed-in users?"

<Tip>
  If you have not decided how the widget should identify visitors yet, read **[Authentication](/widget/authentication)** first.
</Tip>

<Info>
  Want to try single-session mode and other session behaviors in one click? Open the **[Playground](/widget/playground)** and flip the toggles live.
</Info>

## How A Conversation Flows

```mermaid theme={"dark"}
flowchart LR
  A([Visitor opens widget]) --> B[Start or resume conversation]
  B --> C[AI responds in the same thread]
  C --> D[Issue resolved or needs more help]
  D -->|Resolved| E([Conversation can be resolved])
  D -->|Human| F([Human handoff in the same thread])

  style A fill:#1a5c20,color:#fff,stroke:#267a2e
  style E fill:#1a5c20,color:#fff,stroke:#267a2e
  style F fill:#1a5c20,color:#fff,stroke:#267a2e
```

<Info>
  Whether the AI keeps the conversation, resolves it, or hands it to a person depends on your support setup and escalation rules. For the policy side, see [Human Handoff](/handoff/introduction).
</Info>

## What Counts As A Session

A **session** is one conversation thread inside the widget. Visitors can have open and resolved sessions, and the widget can show a list of earlier conversations when that fits your setup.

<AccordionGroup>
  <Accordion title="New conversation" icon="plus">
    A new session starts when the visitor opens a new thread and sends a message.
  </Accordion>

  <Accordion title="Returning conversation" icon="clock">
    Returning visitors can reopen existing threads instead of starting from scratch, as long as the widget can still identify them.
  </Accordion>

  <Accordion title="Resolved conversation" icon="circle-check">
    Resolved sessions remain part of the visitor's history, but they are no longer active chat threads.
  </Accordion>
</AccordionGroup>

## How Returning History Works

History access depends on how you identify the visitor:

<AccordionGroup>
  <Accordion title="Anonymous" icon="user">
    Best for low-friction support. History stays tied to the same browser session.
  </Accordion>

  <Accordion title="Non-verified" icon="id-card">
    Good for personalization, but not strong identity across devices.
  </Accordion>

  <Accordion title="Verified" icon="shield-check">
    Best when signed-in customers should keep conversation history across devices.
  </Accordion>
</AccordionGroup>

<Note>
  Verified and non-verified conversation histories are treated differently. If a user sometimes loads the widget with a verified identity and sometimes without one, the history experience will not be the same across those cases.
</Note>

## Session Rules That Affect The Visitor Experience

These configuration choices change what visitors can do:

<AccordionGroup>
  <Accordion title="Only allow one open conversation" icon="messages">
    **Default:** Visitors can have multiple open conversations.

    **What changes:** <Tooltip>`oneOpenSessionAllowed: true`</Tooltip> hides the new-conversation option while an open thread already exists.

    **Choose this when:** You want visitors to stay focused on one active issue at a time.
  </Accordion>

  <Accordion title="Skip the sessions screen" icon="forward">
    **Default:** The widget can show a sessions list before entering chat.

    **What changes:** <Tooltip>`router.chatScreenOnly`</Tooltip> removes the sessions browser and lands the visitor directly in the chat experience.

    **Choose this when:** You want the widget to feel like a single-thread support chat instead of a small inbox.
  </Accordion>

  <Accordion title="Go straight to chat when there is no history" icon="arrow-right">
    **Default:** First-time visitors may pass through the sessions logic before entering chat.

    **What changes:** <Tooltip>`router.goToChatIfNoSessions`</Tooltip> takes first-time visitors directly into the chat flow when there is nothing to resume.

    **Choose this when:** You want less friction for brand-new visitors.
  </Accordion>

  <Accordion title="Resolve from the widget header" icon="circle-check">
    **Default:** Visitors continue using the conversation until your flow or team closes it.

    **What changes:** Adding the <Tooltip>`resolve-session`</Tooltip> header button gives the visitor a direct way to close the conversation from the widget itself.

    **Choose this when:** You want visitors to explicitly mark an issue as done.
  </Accordion>
</AccordionGroup>

## What Handoff Looks Like In The Widget

When the AI <Tooltip href="/handoff/introduction">hands off</Tooltip>, the conversation stays in the same thread. Your visitor does not need to start over somewhere else.

<Steps>
  <Step title="The AI stops owning the conversation">
    The thread stays open, but the AI is no longer the active responder for that issue.
  </Step>

  <Step title="A human agent continues in the same thread">
    Your visitor keeps talking in the same conversation instead of being pushed into a separate support flow.
  </Step>

  <Step title="Your team keeps the conversation context">
    The full conversation remains available to your team so the visitor does not have to repeat everything.
  </Step>

  <Step title="Keep custom UI aligned with session state">
    The widget has no `onHandoff` configuration callback. In a headless integration, read `useSessions().sessionState.session` for the current session state. `hooks.onMessageReceived` reports a newly delivered message; it is not an immediate transfer event and must not drive transfer redirects or confirmations.
  </Step>
</Steps>

<Info>
  Need the decision rules behind handoff? See [Human Handoff](/handoff/introduction) for when the AI escalates, what triggers a human takeover, and how that policy works across channels.
</Info>

## Restore an open session after reload

Set `router.restoreLastSession: true` to reopen the last selected session when it is still open. The default is `false`. The standard widget uses its browser storage; a headless provider needs a storage adapter to persist the pointer. Closing the session or starting a new one clears the saved active-session pointer.

JWT renewal for the same owner preserves the current session. Switching the signed user or account clears the active state before loading the new owner’s history. See [identity renewal](/widget/authentication#renew-identity-without-losing-the-active-session).

## Feedback And Resolution

Two common post-conversation patterns are available:

<Info>
  <Tooltip>`thisWasHelpfulOrNot`</Tooltip> controls the built-in prompt that asks whether the latest AI answer solved the issue. Use it when you want a lightweight “resolved vs still need help” check before the conversation moves on.
</Info>

<AccordionGroup>
  <Accordion title="Helpful or need more help prompt" icon="thumbs-up">
    Use `thisWasHelpfulOrNot` when you want the widget to ask whether the latest AI answer solved the issue.
  </Accordion>

  <Accordion title="CSAT" icon="star">
    The widget can show <Tooltip>CSAT</Tooltip> when your workflow requests it, and headless builds can control the experience with the CSAT hooks.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Authentication" icon="shield-check" href="/widget/authentication">
    Choose the identity model that controls history access.
  </Card>

  <Card title="Configuration" icon="gear" href="/widget/configuration">
    Session rules, routing, prompts, and resolution controls.
  </Card>

  <Card title="Handoff Settings" icon="user-group" href="https://platform.open.cx/settings/handoff">
    Configure when the AI should escalate to a person.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/widget/troubleshooting">
    Missing history, repeated prompts, and handoff confusion.
  </Card>
</CardGroup>


# Widget overview
Source: https://docs.open.cx/widget/custom-components

Decide when to replace plain text widget replies with custom UI, and choose the right path for React or headless implementations.

Use <Tooltip>custom components</Tooltip> when a normal chat bubble is not enough. Common examples include account summaries, order status cards, onboarding steps, appointment pickers, and other action results that are easier to use as UI than as plain text.

<Tip>
  If you have not installed the widget yet, start with **[Install Widget](/widget/install-widget)** first.
</Tip>

<Info>
  Custom components sit on top of the default widget UI — use the **[Playground](/widget/playground)** to dial in the widget's look first, then layer your action components on top.
</Info>

<Note>
  Action-result components and the agent-generated rich-reply catalog are separate. Registering a message renderer does not make a new component available to the agent. Widget 5.0.0 does not add customer-defined rich-reply catalogs or generic rich forms.
</Note>

## When Custom Components Are Worth It

<AccordionGroup>
  <Accordion title="Structured action results" icon="bolt">
    Use custom components when your AI action returns data that should be presented as a card, table, summary, or interactive block.
  </Accordion>

  <Accordion title="Guided flows" icon="sliders">
    Use custom components or <Tooltip>`modesComponents`</Tooltip> when a visitor should move through a richer flow than normal back-and-forth chat.
  </Accordion>

  <Accordion title="Safer fallback UI" icon="shield">
    Use a component with a clear fallback state when an action may return incomplete or unexpected data.
  </Accordion>
</AccordionGroup>

## Choose Your Path

<CardGroup>
  <Card title="React Components" icon="react" href="/widget/custom-components-react">
    Best when you use the default React widget and want to register components by action key.
  </Card>

  <Card title="Headless" icon="code" href="/widget/custom-components-headless">
    Best when you own the renderer, routing, or storage layer and need full control over message UI.
  </Card>
</CardGroup>

## Two Kinds Of Advanced Widget UI

Do not mix these concepts together:

<CardGroup>
  <Card title="Action result components" icon="bolt" href="/widget/custom-components-react">
    Render a custom UI after the AI calls an action and gets structured data back.
  </Card>

  <Card title="Conversation mode components" icon="rectangle-list" href="/widget/configuration#advanced-ui-conversation-modes">
    Render a dedicated UI for an active mode or canvas flow with `modesComponents`.
  </Card>
</CardGroup>

Both are valid. Pick the one that matches whether you are rendering a **result** or driving a **flow**.

***

## Related Documentation

<CardGroup>
  <Card title="React Components" icon="react" href="/widget/custom-components-react">
    Register action-specific UI in the default React widget.
  </Card>

  <Card title="Headless" icon="code" href="/widget/custom-components-headless">
    Build custom rendering with the headless widget packages.
  </Card>

  <Card title="Configuration" icon="gear" href="/widget/configuration">
    Use `modesComponents`, styling, and behavior options together.
  </Card>

  <Card title="Headless" icon="code" href="/widget/custom-components-headless">
    Build custom rendering with the headless widget packages.
  </Card>
</CardGroup>


# Headless widget setup and hooks
Source: https://docs.open.cx/widget/custom-components-headless

Build custom widget rendering with the headless packages when you need your own UI, routing, or storage model.

Use `@opencx/widget-react-headless` when your application owns the chat UI, rendering, navigation and persistence. For the standard widget with a few custom slots, use [React components](/widget/custom-components-react).

This reference targets Widget 5.0.0. [Check publication and matching package versions](/widget/install-widget#choose-your-version) before installing.

## Required setup

`WidgetProvider` requires a nonempty `components` array containing `fallback`. It checks this when the provider renders, even if your own message list does not use the registry. Unlike the standard `<Widget>`, it does not supply default renderers or browser storage.

```tsx widget-components.tsx theme={"dark"}
import type {
  WidgetComponentProps,
  WidgetComponentType,
} from '@opencx/widget-react-headless';

export function TextMessage(props: WidgetComponentProps) {
  if (props.type === 'SYSTEM') return null;
  return <p>{props.data.message}</p>;
}

export const components: WidgetComponentType[] = [
  { key: 'fallback', component: TextMessage },
  { key: 'bot_message', component: TextMessage },
  { key: 'agent_message', component: TextMessage },
];
```

Pass a storage adapter if identity and session selection should survive a page reload:

```tsx Support.tsx theme={"dark"}
import { WidgetProvider } from '@opencx/widget-react-headless';
import type { ExternalStorage } from '@opencx/widget-core';
import { components } from './widget-components';
import { CustomWidget } from './CustomWidget';

const storage: ExternalStorage = {
  async get(key) { return localStorage.getItem(key); },
  async set(key, value) { localStorage.setItem(key, value); },
  async remove(key) { localStorage.removeItem(key); },
};

export function Support() {
  return (
    <WidgetProvider
      options={{ token: '<WIDGET_TOKEN>', streaming: false }}
      components={components}
      storage={storage}
      loadingComponent={<p>Loading support…</p>}
      errorComponent={() => <p>Support could not load. Please try again.</p>}
    >
      <CustomWidget />
    </WidgetProvider>
  );
}
```

Mount this in your client-side app. Your UI must handle contact collection when configured, empty history, attachments, send errors, resolved sessions and identity changes. The snippets above establish the provider contract; they do not supply that application UI.

## Render and send polling messages

The following component renders persisted text messages and sends a message through the same widget session. It is a minimal polling surface; add session navigation, contact collection, attachments, system-message handling and your required error states before shipping.

```tsx CustomWidget.tsx theme={"dark"}
import { useState } from 'react';
import {
  useMessages,
  useSessions,
  useWidget,
} from '@opencx/widget-react-headless';

export function CustomWidget() {
  const { messagesState, sendMessage } = useMessages();
  const { sessionState } = useSessions();
  const { componentStore } = useWidget();
  const [text, setText] = useState('');
  const [failed, setFailed] = useState(false);
  const disabled = messagesState.isSendingMessage ||
    sessionState.session?.isOpened === false;

  return (
    <section aria-label="Support">
      {messagesState.messages.map((message) => {
        if (message.type === 'USER') {
          return <p key={message.id}>{message.content}</p>;
        }
        if (message.type === 'SYSTEM') return null;
        const Component = componentStore.getComponent(message.component) ??
          componentStore.getComponent('fallback');
        return Component ? <Component key={message.id} {...message} /> : null;
      })}
      <form onSubmit={async (event) => {
        event.preventDefault();
        if (disabled || !text.trim()) return;
        setFailed(false);
        try {
          await sendMessage({ content: text });
          setText('');
        } catch {
          setFailed(true);
        }
      }}>
        <input
          aria-label="Message"
          value={text}
          disabled={disabled}
          onChange={(event) => setText(event.target.value)}
        />
        <button disabled={disabled || !text.trim()}>Send</button>
      </form>
      {failed && <p role="alert">Message could not be sent. Please try again.</p>}
    </section>
  );
}
```

Persisted messages are discriminated by `type`. User messages have `content`; AI and human messages have `data.message`; system messages have a `subtype` and their own payload. Narrow the type before reading `data.action`. Do not assume every message has `data.content`.

## Provider props

| Prop | Contract |
| - | - |
| `options` | Required `WidgetConfig`, including the organization widget token. |
| `children` | Your UI. Hooks must run below the provider. |
| `components` | Required at runtime; include `fallback`. Registration keys are case-insensitive. |
| `storage` | Optional `ExternalStorage` with asynchronous `get`, `set` and `remove`. Omission does not persist browser identity for you. |
| `loadingComponent` | Optional rendered node while initialization is pending. |
| `errorComponent` | Optional function from an initialization error to rendered UI. Omission logs the error and renders nothing. This does not repair an invalid component registry. |

Use stable renderer and storage objects. Update `options.user.token` on the existing provider for renewal; do not key the provider by the token string, which would remount it unnecessarily. See [identity renewal](/widget/authentication#renew-identity-without-losing-the-active-session).

## Hooks reference

Use the declarations from your installed version for full signatures. The table below lists the entry points and the state they own.

| Hook | What it provides |
| - | - |
| `useMessages()` | `messagesState`, `sendMessage`, `rememberSentText`, `getSentTextHistory`. Streaming also sets the effective sending flags while a reply is active. |
| `useSessions()` | `sessionState`, `sessionsState`, `openSessions`, `closedSessions`, `loadMoreSessions`, `resolveSession`, `createStateCheckpoint`, `canCreateNewSession`. |
| `useWidgetRouter()` | `routerState`, `toSessionsScreen`, `toChatScreen`. Pass an existing session ID to open it; omit the ID to start a new empty session. |
| `useContact()` | `contactState` and `createUnverifiedContact` for a contact form you implement. Browser-supplied data is not verified identity. |
| `useConfig()` | The current widget configuration. |
| `useBot()` | Configured bot identity for your message UI. |
| `useIsAwaitingBotReply()` | A reply-wait flag for your typing indicator. |
| `useUploadFiles()` | Upload queue, progress, cancellation and completed files. You must include successful attachment metadata when sending. When **File uploads** is off in Web chat settings, uploads and messages with files are refused; hide your upload control for that organization. |
| `useCsat()` | Feedback request/submission state and `submitCsat`. |
| `useModes()` | Available modes, active mode and configured mode component. |
| `useDocumentDir()` | The resolved text direction for your UI. |
| `useWidget()` | Configuration, the widget context, renderer registry and package version. Prefer the scoped hooks above. |
| `usePrimitiveState()` | Subscribe to a state value exposed by the core package when a higher-level hook is insufficient. |
| `useAgentChatUi()` | Live response, persisted rich-turn sources, Stop, retries, queue, questions, connections and page-effect state. |

### Launcher and layout providers

Wrap consumers of `useWidgetTrigger()` in `WidgetTriggerProvider`. It provides `isOpen` and `setIsOpen` for an external launcher. `useWidgetLayout()` requires `WidgetLayoutProvider` inside `WidgetProvider` and exposes Companion layout state. Neither provider creates a launcher or panel UI for a headless client.

`useCompanionChats()` exposes Companion session management. `useComposerDraft()` keeps a composer draft with that session state. These are presentation helpers; enabling them does not opt into streaming or page access.

### Session status and handoff

Observe `useSessions().sessionState.session` to render current session state. There is no `onHandoff` widget option. `hooks.onMessageReceived` runs when a new non-user message arrives, with that message and its session; it does not guarantee a callback at the moment of transfer. Do not use it as a replacement for an immediate transfer notification.

### Ask whether a reply helped

`useMessages().messagesState.lastAIResMightSolveUserIssue` is `true` when the latest AI reply might have solved the visitor's issue. Use it to show your own "This was helpful" / "I need more help" prompt or to start a feedback request.

* It resets to `false` when the visitor sends a message and is set once the AI reply completes, with polling and with streaming. Streaming sets it from widget version 5.4.1.
* It stays `false` when the session is handed off to a teammate, when the visitor stops the reply, and when a newer message is already waiting for its turn.
* To change when the AI counts a reply as possibly solving the issue, write your own rule under **Might Solve User Issue** in [Settings → Autopilot](https://platform.open.cx/settings/autopilot).

## Add streaming deliberately

Set `options.streaming: true` only after your UI handles streaming and your organization supports it. Omitted or false keeps polling. `useAgentChatUi()` returns inactive defaults when the streaming engine is not active.

| State or callback | Rendering responsibility |
| - | - |
| `liveItems`, `liveTurnKey` | Render the active response as it arrives. |
| `turnSources` | Render completed rich turns and history without duplicating persisted transcript rows they replace. |
| `isStreaming`, `stop` | Show progress and allow the visitor to stop. Stopping does not discard queued messages. |
| `queuedUserMessages`, `removeQueued` | Show messages waiting for a turn and let the visitor remove them. A second message can also steer the current task. |
| `turnFailed`, `retryFailedTurn` | Show a failure and allow a retry. |
| `resumeInterruptedTurn` | Resume a reply cut off by a dropped connection. Browsers call it when the tab is visible again or the network returns; call it yourself where neither event exists, such as [React Native](#stream-in-react-native). |
| `pendingClarification` | Render and submit the agent's supported selectable question interaction. |
| `pendingConnection` | Render account connection requests using the connection flow. |
| `pageEffects`, `pendingPageAction` | Handle page interactions with permission checks, visitor consent and a reply describing the actual outcome. |

Apply your configured presentation restrictions to both live items and saved history. The exported `applyPresentation` helper applies the supported visibility policy. The standard widget implements this rendering; a headless UI must supply it.

Declare `capabilities.richReplies`, `capabilities.structuredQuestions` or `capabilities.pageEffects` only after you implement that interaction. Leave unsupported flags off so the agent uses ordinary replies. Page actions require all relevant organization and embed permissions plus a consent implementation; simply advertising `pageEffects` does not implement one.

For personal connections, `capabilities.connections: true` is also required. Use `useConnection()` only after implementing the corresponding UI and signed account flow. See [Connections](/widget/connections).

## Stream in React Native

Streaming in a React Native app needs Widget 5.1.0 or later and Expo SDK 52 or later. Install matching widget packages and the two polyfills the stream reader needs:

```bash theme={"dark"}
npm install @opencx/widget-react-headless@^5.1.0 @opencx/widget-core@^5.1.0 @ungap/structured-clone @stardazed/streams-text-encoding
```

Add the polyfills in their own file and import it first in your app entry (with Expo Router, the root `app/_layout.tsx`), before anything that loads the widget:

```ts polyfills.ts theme={"dark"}
import { polyfillGlobal } from 'react-native/Libraries/Utilities/PolyfillFunctions';
import structuredClone from '@ungap/structured-clone';
import { TextDecoderStream } from '@stardazed/streams-text-encoding';

if (!('structuredClone' in globalThis)) {
  polyfillGlobal('structuredClone', () => structuredClone);
}
if (!('TextDecoderStream' in globalThis)) {
  polyfillGlobal('TextDecoderStream', () => TextDecoderStream);
}
```

```tsx app/_layout.tsx theme={"dark"}
import '../polyfills';
```

Pass a streaming `fetch`. React Native's built-in `fetch` cannot read a reply while it arrives, so `streamingFetch` takes the one from `expo/fetch`. Every other widget request keeps using the global `fetch`.

```tsx SupportChat.tsx theme={"dark"}
import { fetch as expoFetch } from 'expo/fetch';
import { WidgetProvider } from '@opencx/widget-react-headless';

<WidgetProvider
  components={components}
  options={{
    token: '<WIDGET_TOKEN>',
    streaming: true,
    streamingFetch: expoFetch as typeof fetch,
  }}
>
  <YourChat />
</WidgetProvider>;
```

Resume replies on your app's own signals. React Native has no tab visibility, so call `resumeInterruptedTurn` when the app returns to the foreground, and from your connectivity listener when the network returns. It does nothing unless the last reply was cut off.

```tsx ResumeOnForeground.tsx theme={"dark"}
import { useEffect } from 'react';
import { AppState } from 'react-native';
import { useAgentChatUi } from '@opencx/widget-react-headless';

export function ResumeOnForeground() {
  const { resumeInterruptedTurn } = useAgentChatUi();
  useEffect(() => {
    const subscription = AppState.addEventListener('change', (state) => {
      if (state === 'active') resumeInterruptedTurn();
    });
    return () => subscription.remove();
  }, [resumeInterruptedTurn]);
  return null;
}
```

Render `<ResumeOnForeground />` inside `WidgetProvider`, next to your chat UI.

Voice dictation is not available in React Native.

## Custom action-result components

Match an action's component key and validate its result before rendering. For example:

```tsx BalanceMessage.tsx theme={"dark"}
import type { WidgetComponentProps } from '@opencx/widget-react-headless';

export function BalanceMessage(props: WidgetComponentProps) {
  if (props.type !== 'AI') return null;
  const result = props.data.action?.data;
  if (typeof result !== 'object' || result === null ||
      !('balance' in result) || typeof result.balance !== 'number' ||
      !('currency' in result) || typeof result.currency !== 'string') {
    return <p>{props.data.message}</p>;
  }
  return <p>{result.balance} {result.currency}</p>;
}
```

Add `{ key: 'getAccountBalance', component: BalanceMessage }` to the registry for an action that emits that key. `components` is a message/action renderer registry. It does not register a new type in the agent-generated rich-reply catalog. Generic rich forms and customer-defined rich-reply catalogs are not provided by this release.

## Verify your headless UI

* Test first contact creation, existing and resolved sessions, error UI, attachments and human replies.
* Test persistence after reload with your storage adapter.
* Renew a verified token for the same user, then switch accounts and log out. Confirm the old session is not rendered under another identity.
* If streaming is enabled, test live output, Stop, retry, queued messages and history without duplicate rows.
* In React Native, background the app mid-reply and bring it back, and drop and restore connectivity mid-reply. Confirm the reply finishes once.
* If you replace a standard renderer, verify every capability you advertise, including visitor approval and stale page targets.

See [Migrate to v5](/widget/migrate-to-v5) for the compatibility checklist and [Configuration reference](/widget/configuration-reference) for the shared options.


# React Components
Source: https://docs.open.cx/widget/custom-components-react

Render AI action results with custom React components in the default AI Chat Widget.

Use this page when you are using `@opencx/widget-react` and want specific AI action results to render as custom React UI.

<Tip>
  Need the broader concept first? Start with **[Custom Components](/widget/custom-components)**. Want to try widget options live without installing anything? Open the **[Playground](/widget/playground)**.
</Tip>

## How React Component Mapping Works

For the default React widget, you register an array of components on <Tooltip>`<Widget />`</Tooltip>.

Each entry needs:

* a `key`
* a React `component`

The `key` must match the action <Tooltip>operation\_id</Tooltip> in camelCase.

## Step 1: Build The Component

Use <Tooltip>`WidgetComponentProps<T>`</Tooltip> so your component is typed to the action result you expect.

```tsx AccountBalanceCard.tsx theme={"dark"}
import type { WidgetComponentProps } from '@opencx/widget-react-headless';

type AccountBalancePayload = {
  balance: number;
  currency: string;
};

export function AccountBalanceCard(props: WidgetComponentProps<AccountBalancePayload>) {
  if (props.type !== 'AI') return null;
  const result = props.data.action?.data;

  if (!result || typeof result.balance !== 'number' || typeof result.currency !== 'string') {
    return <div>Balance details are not available right now.</div>;
  }

  return (
    <div>
      <strong>Available balance</strong>
      <div>
        {result.balance} {result.currency}
      </div>
    </div>
  );
}
```

## Step 2: Register It On The Widget

```tsx WidgetWrapper.tsx theme={"dark"}
import { Widget } from '@opencx/widget-react';
import { AccountBalanceCard } from './AccountBalanceCard';

export function WidgetWrapper() {
  return (
    <Widget
      options={{
        token: '<WIDGET_TOKEN>',
      }}
      components={[
        {
          key: 'getAccountBalance',
          component: AccountBalanceCard,
        },
      ]}
    />
  );
}
```

## Rich replies and renderer overrides

The `components` prop registers message and action-result renderers. It does not add customer-defined component types to the agent's rich-reply catalog. Generic rich forms and customer-defined rich-reply catalogs are not included in Widget 5.0.0.

The standard widget supplies fallback, AI, human and streaming renderers. If you replace message or rich-reply renderers, explicitly declare only the `capabilities` your replacements implement. Check both live replies and saved history; rendering an action result does not implement selectable questions or page effects. See [capability declarations](/widget/configuration-reference#capabilities).

Custom AI and human reply renderers can receive `replyTo` with a quoted message and sender. Preserve that identity when displaying quotes; handle a quote whose target is not loaded yet.

## What To Watch For

<AccordionGroup>
  <Accordion title="Key mismatch" icon="key">
    If the component key does not match the action `operation_id`, the widget will not use your custom component.
  </Accordion>

  <Accordion title="Unexpected payload shape" icon="triangle-exclamation">
    Always render a fallback when `data?.action?.data` is missing or incomplete.
  </Accordion>

  <Accordion title="Keep the component narrow" icon="sliders">
    Focus each component on one action result. If a component tries to handle many unrelated actions, it becomes hard to trust and maintain.
  </Accordion>
</AccordionGroup>

## Good React Use Cases

<CardGroup>
  <Card title="Account and order summaries" icon="rectangle-list">
    Show balances, plans, shipments, invoices, or usage totals as structured UI.
  </Card>

  <Card title="Status and confirmation cards" icon="circle-check">
    Show action outcomes like refunds, appointment bookings, or case updates in a clearer format.
  </Card>

  <Card title="Mini workflows" icon="sliders">
    Collect a few related inputs or guide the visitor through the next step after a successful action.
  </Card>

  <Card title="Rich fallback states" icon="wrench">
    Give visitors a clear next step when the action returns partial data or nothing useful.
  </Card>
</CardGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Custom Components" icon="paintbrush" href="/widget/custom-components">
    Decide when custom UI is worth the added complexity.
  </Card>

  <Card title="Headless" icon="code" href="/widget/custom-components-headless">
    Build fully custom rendering when the default widget is not enough.
  </Card>

  <Card title="Configuration" icon="gear" href="/widget/configuration">
    Use widget behavior and mode configuration alongside custom UI.
  </Card>

  <Card title="Playground" icon="play" href="/widget/playground">
    Try widget options in a live form and copy the generated snippet.
  </Card>
</CardGroup>


# Install Widget
Source: https://docs.open.cx/widget/install-widget

Launch the AI Chat Widget on your website with HTML, the default React package, or a headless build.

Use this page when your goal is simple: get the **AI Chat Widget** live on a website and confirm visitors can start a session.

<Tip>
  Need the widget to recognize signed-in customers? Open **[Authentication](/widget/authentication)** after installation.
</Tip>

<Info>
  Want to tweak colors, launcher size, and initial messages before you copy the code? Use the **[Playground](/widget/playground)** — it generates the exact snippet for your setup.
</Info>

## Before You Start

You need a <Tooltip>**widget token**</Tooltip> from your [OpenCX dashboard](https://platform.open.cx/channels/configure/widget). This token tells the widget which organization it belongs to.

Choose the install path that matches your site:

<CardGroup>
  <Card title="HTML" icon="code">
    Best when you want the fastest website embed.
  </Card>

  <Card title="React" icon="react">
    Best when your site already uses React.
  </Card>

  <Card title="Headless" icon="cube">
    Best when you want your own UI or storage model.
  </Card>

  <Card title="Mobile" icon="phone" href="/widget/native-mobile">
    Best when you need chat inside iOS, Android, or React Native.
  </Card>
</CardGroup>

## Choose your version

These examples target **Widget 5.0.0**. Check that the version has been published before installing it:

```bash theme={"dark"}
npm view @opencx/widget-react@5.0.0 version
npm view @opencx/widget-react dist-tags --json --prefer-online
```

If `5.0.0` is not available yet, keep your current tested version until the release is published. An older beta does not include all the behavior described here.

Pin `4.0.63` explicitly to stay on v4. The `latest` tag can move to a new major; it is not a v4 version pin. Keep every directly installed OpenCX widget package on the same exact version.

<Tip>
  Prefer help from your coding assistant? [Install the widget integration skill](/widget/agent-skills) with `npx`, then ask it to configure v5 in your application. Upgrading an existing widget? Start with [Migrate to v5](/widget/migrate-to-v5).
</Tip>

## Implementation Steps

<Tabs>
  <Tab title="HTML">
    <Steps>
      <Step title="Confirm this is the right path">
        Choose HTML when you want the default widget on a standard website and do not need to build custom UI from scratch.
      </Step>

      <Step title="Add the widget script">
        Put the widget script in your page `head`.

        ```html index.html theme={"dark"}
        <script defer src="https://unpkg.com/@opencx/widget@5.0.0/dist-embed/script.js"></script>
        ```
      </Step>

      <Step title="Initialize the widget after the page loads">
        Call <Tooltip>`initOpenScript()`</Tooltip> after `DOMContentLoaded` and pass your widget token.

        ```html index.html theme={"dark"}
        <script>
          window.addEventListener('DOMContentLoaded', () => {
            initOpenScript({
              token: '<WIDGET_TOKEN>',
            });
          });
        </script>
        ```
      </Step>

      <Step title="Reload the page and verify the widget">
        By default, the widget appears as a floating launcher. Open it and send a test message.
      </Step>
    </Steps>

    <Warning>
      **Widget does not appear after page load:** keep the `DOMContentLoaded` wrapper unless your site guarantees the widget initializes only after the DOM is ready.
    </Warning>
  </Tab>

  <Tab title="React">
    <Steps>
      <Step title="Confirm this is the right path">
        Choose React when your website already uses React and you want the default widget experience inside your app.
      </Step>

      <Step title="Install the package">
        Add the default widget package to your project.

        ```bash theme={"dark"}
        npm install @opencx/widget-react@5.0.0
        ```
      </Step>

      <Step title="Create a wrapper component">
        Render <Tooltip>`<Widget />`</Tooltip> and pass your widget token through `options`.

        ```tsx WidgetWrapper.tsx theme={"dark"}
        import { Widget } from '@opencx/widget-react';

        export function WidgetWrapper() {
          return (
            <Widget
              options={{
                token: '<WIDGET_TOKEN>',
              }}
            />
          );
        }
        ```
      </Step>

      <Step title="Mount it in your app">
        Place the wrapper where the widget should be available, usually your app shell or main layout.
      </Step>
    </Steps>

    <Warning>
      **Widget renders but never loads your organization:** make sure the widget token is passed inside the `options` object you give to `<Widget />`.
    </Warning>
  </Tab>

  <Tab title="Headless">
    <Steps>
      <Step title="Confirm this is the right path">
        Choose <Tooltip>headless</Tooltip> only when the default widget UI is not enough and your team wants to own the layout, rendering, and persistence model.
      </Step>

      <Step title="Install the headless packages">
        Add the provider and core engine packages.

        ```bash theme={"dark"}
        npm install @opencx/widget-react-headless@5.0.0 @opencx/widget-core@5.0.0
        ```
      </Step>

      <Step title="Wrap your custom UI with WidgetProvider">
        <Tooltip>`WidgetProvider`</Tooltip> initializes the widget engine and gives your app access to the hooks and state you need.

        ```tsx App.tsx theme={"dark"}
        import { WidgetProvider } from '@opencx/widget-react-headless';
        import type { WidgetComponentProps } from '@opencx/widget-react-headless';
        import { CustomWidget } from './CustomWidget';

        function FallbackMessage(props: WidgetComponentProps) {
          if (props.type === 'SYSTEM') return null;
          return <p>{props.data.message}</p>;
        }

        const components = [{ key: 'fallback', component: FallbackMessage }];

        export function App() {
          return (
            <WidgetProvider
              options={{ token: '<WIDGET_TOKEN>', streaming: false }}
              components={components}
            >
              <CustomWidget />
            </WidgetProvider>
          );
        }
        ```
      </Step>

      <Step title="Build and test the full session flow">
        A headless provider requires a nonempty `components` array containing `fallback`; it does not install the standard renderers. Provide a `storage` adapter to persist identity across reloads. Follow the [complete headless example](/widget/custom-components-headless), then check history, sends, handoff and returning visitors.
      </Step>
    </Steps>

    <Warning>
      **Headless UI works for new chats but breaks on real usage:** remember that you own fallback states, history rendering, and resolved-session behavior in a headless build.
    </Warning>
  </Tab>
</Tabs>

## Bring Companion into the widget

The default display remains the classic corner popover. Set `displayMode: 'companion'` to use the v5 floating workspace:

```tsx theme={"dark"}
<Widget
  options={{
    token: '<WIDGET_TOKEN>',
    displayMode: 'companion',
  }}
/>
```

For HTML, pass the same `displayMode` option to `initOpenScript`. Companion layout and streaming are separate: live replies require both `streaming: true` in the embed and organization support. Omitted or false keeps polling, including with Companion. See [Companion mode](/widget/companion-mode) for layouts, feature controls, page context and annotations.

## Choose How The Widget Appears

These options control what visitors see on the page before they even start chatting.

<AccordionGroup>
  <Accordion title="Floating launcher (default)" icon="message">
    This is the standard widget behavior. Visitors see a launcher button, click it to open the widget, and close it when they are done.

    Use this when the widget should be available site-wide without taking up permanent page space.

    ```tsx theme={"dark"}
    const options = {
      token: '<WIDGET_TOKEN>',
    };
    ```
  </Accordion>

  <Accordion title="Inline embed" icon="rectangle-list">
    Use this when the widget should live inside a page section, such as a help page, pricing page, portal, or account screen.

    When <Tooltip>`inline`</Tooltip> is `true`, the widget stays open inside its parent container and the floating launcher is hidden. In practice, this means the widget becomes part of the page layout instead of hovering over it.

    ```tsx theme={"dark"}
    const options = {
      token: '<WIDGET_TOKEN>',
      inline: true,
    };
    ```
  </Accordion>

  <Accordion title="Open by default" icon="arrow-up-right-from-square">
    Use this when the widget should already be open on first render, such as inside a webview or a dedicated support page.

    This changes the initial state only. The visitor can still continue using the widget normally after it opens.

    ```tsx theme={"dark"}
    const options = {
      token: '<WIDGET_TOKEN>',
      isOpen: true,
    };
    ```
  </Accordion>

  <Accordion title="Open after a delay" icon="clock">
    Use this when you want the widget to open after the visitor has already spent time on the page.

    This is best for proactive support moments. It is usually a poor fit for every page on your site because it can feel intrusive if the visitor was not trying to chat.

    ```tsx theme={"dark"}
    const options = {
      token: '<WIDGET_TOKEN>',
      openAfterNSeconds: 10,
    };
    ```
  </Accordion>
</AccordionGroup>

## Test Your First Session

<CardGroup>
  <Card title="1. Confirm the widget appears" icon="list-ol">
    Load the page and verify the launcher or inline widget shows where you expect.
  </Card>

  <Card title="2. Confirm the opening behavior" icon="list-ol">
    Check that the widget opens the way you configured it: floating, inline, already open, or delayed.
  </Card>

  <Card title="3. Send a real message" icon="list-ol">
    Start a session and verify the message reaches your [inbox](https://platform.open.cx/inbox).
  </Card>

  <Card title="4. Reload and return" icon="list-ol">
    Refresh the page and confirm the same visitor can continue the session on the same device.
  </Card>
</CardGroup>

## Good To Know

<AccordionGroup>
  <Accordion title="Links can open in the same tab or a new one" icon="link">
    Use <Tooltip>`anchorTarget`</Tooltip> when replies include links and you need to control what happens after the visitor clicks them.

    Choose `_top` if you want the current page to change. Choose `_blank` if you want the visitor to keep the chat open and open the link in a new tab.
  </Accordion>

  <Accordion title="Headless builds can use custom storage" icon="database">
    If browser storage is not the right fit, use <Tooltip>`ExternalStorage`</Tooltip> from `@opencx/widget-core`.

    This matters most in mobile apps, embedded environments, or custom shells where your app already controls how tokens and session data are stored.
  </Accordion>
</AccordionGroup>

## Where To Go Next

<CardGroup>
  <Card title="Authentication" icon="shield-check" href="/widget/authentication">
    Identify signed-in visitors and protect conversation history.
  </Card>

  <Card title="Configuration" icon="gear" href="/widget/configuration">
    Control branding, prompts, behavior, and advanced options.
  </Card>

  <Card title="Widget Sessions" icon="route" href="/widget/conversation-sessions">
    Understand history, handoff, and returning-visitor behavior.
  </Card>

  <Card title="Mobile Support" icon="phone" href="/widget/native-mobile">
    Add the widget to iOS, Android, and React Native apps.
  </Card>
</CardGroup>


# Widget overview
Source: https://docs.open.cx/widget/introduction

Add AI chat to your website, recognize returning visitors, hand sessions to your team, and customize the experience for your brand.

The **AI Chat Widget** lets visitors start support sessions directly on your website. You can launch it as a floating widget, embed it inside a page, or build your own UI on top of the same widget engine.

<Tip>
  New here? Start with **[Install Widget](/widget/install-widget)**, then come back for identity, customization, and advanced UI.
</Tip>

<Info>
  Want to see the widget in action before installing? The **[Playground](/widget/playground)** lets you tweak colors, launcher size, initial messages, and more live — then copy the generated snippet straight into your site.
</Info>

## Widget v5: Companion, right where you need it

Widget v5 brings Companion into your website. A small launcher opens into a floating workspace; visitors can switch to a sidebar or fullscreen, ask about the page they are viewing, and attach a marked screenshot with a note. Embeds that opt into supported streaming show answers as they arrive. Page assistance also requires explicit permissions; changing the layout does not enable it.

<Info>
  These guides describe Widget 5.0.0. Follow [Install Widget](/widget/install-widget#choose-your-version) to check availability and pin your chosen version. Existing v4 users can retain the classic popover, polling and authentication setup when upgrading.
</Info>

<CardGroup>
  <Card title="Companion mode" icon="sparkles" href="/widget/companion-mode">
    Add the floating workspace, page context, annotations and mentions to your site.
  </Card>

  <Card title="AI coding skills" icon="terminal" href="/widget/agent-skills">
    Install a skill to help your coding assistant set up or upgrade your widget.
  </Card>

  <Card title="Migrate to v5" icon="arrow-up" href="/widget/migrate-to-v5">
    Upgrade an existing integration and check custom UI, script hosting and session history.
  </Card>

  <Card title="Web chat settings" icon="sliders" href="https://platform.open.cx/channels/configure/widget">
    Preview the widget and configure website features, with a link to Advanced settings for agent-wide capabilities.
  </Card>
</CardGroup>

## Core Functionality

<AccordionGroup>
  <Accordion title="Launch on your website" icon="rocket">
    Add the widget with a simple script, the default React package, or a headless build. Choose the path that fits your site and team.
  </Accordion>

  <Accordion title="Embed inside mobile apps" icon="phone">
    Use a mobile WebView support screen when iOS, Android, or React Native users should get the same AI chat, history, and handoff experience.
  </Accordion>

  <Accordion title="Recognize the right visitor" icon="shield-check">
    Support anonymous visitors, collect name and email in the widget, or authenticate signed-in customers from your server for stronger identity and cross-device history.
  </Accordion>

  <Accordion title="Keep conversation history organized" icon="messages">
    Visitors can return to earlier conversations, continue open ones, and start new ones when needed. History behavior depends on how you identify the visitor.
  </Accordion>

  <Accordion title="Match your site experience" icon="paintbrush">
    Control branding, copy, launcher behavior, inline embedding, welcome prompts, routing, and deeper styling without rebuilding the entire widget.
  </Accordion>

  <Accordion title="Third-Party Integrations" icon="plug">
    Connect helpdesks and CRMs from the [integrations settings](https://platform.open.cx/settings/integrations). Keep the widget on your site while your team works from the tools they already use.
  </Accordion>

  <Accordion title="Escalate to a human" icon="user-group">
    When the AI <Tooltip href="/handoff/introduction">hands off</Tooltip>, the conversation stays in the same thread. Your team can continue from the inbox, and you can listen for widget handoff events if you want custom UI.
  </Accordion>

  <Accordion title="Render richer UI" icon="bolt">
    Turn AI action results into cards, status views, account summaries, onboarding flows, and other <Tooltip href="/widget/custom-components">custom interfaces</Tooltip> instead of plain text replies.
  </Accordion>

  <Accordion title="Support files and feedback" icon="paperclip">
    Visitors can upload files, and the widget can show post-conversation <Tooltip>CSAT</Tooltip> when your workflow requests it.
  </Accordion>
</AccordionGroup>

<Info>
  The widget works well as a first-response layer on your website: visitors can start with AI, stay in the same thread as the conversation evolves, and move to a human without being pushed into a separate support flow.
</Info>

## Integration Options

<Tabs>
  <Tab title="Drop-in widget">
    Choose this path when you want to add support chat to your site quickly and keep the default widget experience.

    <Steps>
      <Step title="Install the widget">
        Start with [Install Widget](/widget/install-widget) to choose HTML, React, or headless setup.
      </Step>

      <Step title="Decide how visitors are identified">
        Use [Authentication](/widget/authentication) when signed-in customers should keep history across devices.
      </Step>

      <Step title="Tune the experience">
        Use [Configuration](/widget/configuration) for branding, prompts, and behavior.
      </Step>

      <Step title="Extend the UI if needed">
        Use [Custom Components](/widget/custom-components) when plain text replies are not enough.
      </Step>
    </Steps>

    <CardGroup>
      <Card title="Install Widget" icon="plug" href="/widget/install-widget">
        Launch with HTML, React, or headless setup.
      </Card>

      <Card title="Authentication" icon="shield-check" href="/widget/authentication">
        Recognize signed-in visitors and protect chat history.
      </Card>

      <Card title="Configuration" icon="gear" href="/widget/configuration">
        Match the widget to your site, prompts, and behavior.
      </Card>

      <Card title="Mobile Support" icon="phone" href="/widget/native-mobile">
        Add chat inside iOS, Android, and React Native apps.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Third-party integrations">
    The web widget does not have to live on its own. It can be the front door on your website while the rest of the support workflow continues inside the systems your team already uses.

    <AccordionGroup>
      <Accordion title="Zendesk" icon="headset">
        Widget conversations can hand off into [Zendesk](/integrations/zendesk/overview). Your agents pick up with the conversation context already attached.
      </Accordion>

      <Accordion title="Intercom" icon="comment-dots">
        Widget conversations can route into [Intercom](/integrations/intercom/overview) so your team continues the conversation from the Intercom inbox.
      </Accordion>

      <Accordion title="HubSpot" icon="users-viewfinder">
        With [HubSpot](/integrations/hubspot/overview), your team sees CRM context when a widget conversation moves from AI to a human agent.
      </Accordion>

      <Accordion title="Front" icon="inbox">
        Widget conversations can appear in Front so your team can continue support from their shared inbox workflow.
      </Accordion>

      <Accordion title="Other supported integrations" icon="grid-2">
        OpenCX also supports widget handoff and support workflows with [Salesforce](/integrations/salesforce/overview), [Gorgias](/integrations/gorgias/overview), and [Slack](/handoff/introduction).
      </Accordion>
    </AccordionGroup>

    <CardGroup>
      <Card title="Zendesk Integration" icon="headset" href="/integrations/zendesk/overview">
        Set up widget handoff so your team can continue from Zendesk.
      </Card>

      <Card title="All Integrations" icon="grid-2" href="/dashboard/introduction">
        Browse every supported helpdesk and CRM integration.
      </Card>
    </CardGroup>

    <Note>
      Need the broader setup list? See [integrations settings](https://platform.open.cx/settings/integrations). If your main goal is deciding when the AI should escalate, see [handoff settings](https://platform.open.cx/settings/handoff).
    </Note>
  </Tab>
</Tabs>

## Where To Go Next

<CardGroup>
  <Card title="Install Widget" icon="plug" href="/widget/install-widget">
    Choose the HTML, React, or headless implementation path.
  </Card>

  <Card title="Authentication" icon="shield-check" href="/widget/authentication">
    Decide how the widget should recognize visitors.
  </Card>

  <Card title="Configuration" icon="gear" href="/widget/configuration">
    Tune branding, prompts, and behavior.
  </Card>

  <Card title="Mobile Support" icon="phone" href="/widget/native-mobile">
    Add the widget to iOS, Android, and React Native apps.
  </Card>
</CardGroup>


# Migrate the widget from v4 to v5
Source: https://docs.open.cx/widget/migrate-to-v5

Upgrade an existing OpenCX widget to v5. Review package versions, self-hosted scripts, custom rendering, Companion options and session behavior.

Use this guide when upgrading v4 or an earlier v5 beta. Upgrade the package first with your existing configuration, then enable new layouts and capabilities separately.

## Select the release

This guide describes **Widget 5.0.0**. Confirm it is published before using the commands below:

```bash theme={"dark"}
npm view @opencx/widget-react@5.0.0 version
npm view @opencx/widget-react dist-tags --json --prefer-online
```

If 5.0.0 is not available, keep your tested version until publication. Earlier betas do not include all the compatibility changes below. To remain on v4, pin `4.0.63`; `@latest` can move to a new major. Keep the old package versions, script URL and configuration available for rollback.

<Tabs>
  <Tab title="HTML">
    Keep the initialization function and configuration. Change the version in the script URL:

    ```html theme={"dark"}
    <script defer src="https://unpkg.com/@opencx/widget@5.0.0/dist-embed/script.js"></script>
    <script>
      window.addEventListener('DOMContentLoaded', () => {
        window.initOpenScript({ token: '<WIDGET_TOKEN>' });
      });
    </script>
    ```
  </Tab>

  <Tab title="React">
    ```bash theme={"dark"}
    npm install @opencx/widget-react@5.0.0
    ```

    Keep `<Widget options={...} />`. If your app directly imports `@opencx/widget-core` or `@opencx/widget-react-headless`, install them at the same version.
  </Tab>

  <Tab title="Headless">
    ```bash theme={"dark"}
    npm install @opencx/widget-react-headless@5.0.0 @opencx/widget-core@5.0.0
    ```

    Keep the provider, storage adapter and custom UI. Pass a nonempty `components` array containing a `fallback` renderer. See the [headless setup](/widget/custom-components-headless).
  </Tab>
</Tabs>

All directly installed OpenCX widget packages must use the same exact version. The React packages support React 18 and 19. Review your lockfile and any dependency overrides.

## What remains compatible with v4

| Existing setup | Widget 5.0.0 behavior |
| - | - |
| HTML embed | `initOpenScript` and the self-contained `dist-embed/script.js` path remain available. |
| Default layout | The classic popover remains the default; `inline: true` still takes precedence. |
| Polling | Omitted or false `streaming` keeps send/poll delivery, including with the v2 agent and verified users. |
| Authentication | Keep the same server authentication endpoint and `user.token`. The client upgrade does not change chat-only token lifetime. |
| Token renewal | A replacement OpenCX token for the same owner and access scope preserves the active session. Changing user, account or organization resets active state. |
| Customization | Branding, CSS overrides, render slots, header actions, contact forms and starter questions remain configurable. Re-test your own CSS and renderers. |
| Custom user messages | `deliveredAt` remains a compatibility alias; new code can use `timestamp`. |
| Required starter | `requireInitialQuestion` works in v4.0.63 and v5.0.0. Companion shows starters above a disabled composer; the popover hides the composer until selection. |

This is a compatibility contract, not a guarantee for every custom stylesheet, host script or third-party integration. Validate your actual setup before moving an unpinned embed to v5.

## Self-hosted scripts and repeated initialization

Widget 5.0.0's `dist-embed/script.js` is a self-contained classic script. Copying that file is sufficient for the widget code; it does not fetch a separate `widget.js` or additional code chunks. API, attachment and configured asset requests still need your normal host permissions.

Earlier v5 betas used a split loader. Replace that build as one versioned release and keep its old directory available for already-open tabs. Repeated loads of the 5.0.0 script reuse one widget runtime. Initialize one integration on the page; do not mix embed and React mounts in the same root. Test your site's Content Security Policy with the actual script and initializer.

## Review intentional differences

* **HTML sanitization:** agent HTML and footer markup are filtered. Re-test markup and move unsupported presentation into `cssOverrides` or supported custom render slots.
* **Direct schema consumers:** the core package uses `zod` v4 types. Review code that imports its schemas and remove incompatible v3-only overrides.
* **Initialization errors:** the standard widget renders nothing and logs a failure by default. Supply `errorComponent` in a React integration if you need a visible fallback. A missing headless component registry is a setup error that must be fixed separately.
* **Handoff callbacks:** `onHandoff` is not a supported option. `hooks.onMessageReceived` reports a new message, not an immediate handoff event. Do not replace a transfer callback with a message hook and assume equivalent timing.

## Upgrade an earlier v5 beta

Earlier beta integrations may have inherited enabled organization settings. In 5.0.0, opt in explicitly to the features your integration intends to use:

| Feature | Embed opt-in | Additional requirement |
| - | - | - |
| Streamed replies | `streaming: true` | Organization supports streaming. |
| Personal connections | `capabilities.connections: true` | Streaming and a verified token with the intended `mcp_access` scope. |
| Page reading | `features.pageContext: true` | Organization allows page access. |
| Page pointing | Also `features.clientTools: true` | Streaming and a compatible page-effect renderer. |
| Page actions | Also `features.pageActions: true` | Streaming, organization permission and visitor approval for every action. |

Omitted streaming, connections and page flags are off. These client defaults require the upgraded widget; a backend deployment alone does not change an older beta's defaults. To disable page access before upgrading, set all three page flags to `false` explicitly.

Do not enable every flag solely to preserve an old beta's implicit defaults. Enable the features your site uses, with the matching signed account and organization permissions.

## Choose layout and delivery separately

`displayMode: 'companion'` changes presentation. It does not choose the agent version, turn on streaming or grant page permissions. The popover can use supported advanced features too. Inline rendering remains a separate option.

* Omitted or false `streaming` uses polling for saved replies, attachments, human replies and enabled progress updates.
* `streaming: true`, with organization support, streams the live response over Server-Sent Events (SSE). This is not a chat WebSocket connection.
* Polling/history reconciliation still retrieves persisted messages, including human replies and history after reload. It complements the live stream; it does not mean a visitor's message is sent to two agents.
* `presentation.streaming: false` shows complete text while keeping the streaming transport available for live interactions.
* Rich reply generation, selectable follow-up questions and page effects require streaming and supported renderers. Initial starter questions are configuration and work with polling.

See [Companion mode](/widget/companion-mode) for layouts, avatars, bubbles and page permission examples.

## Custom rendering and rich replies

For headless streaming, implement `useAgentChatUi()` alongside the persisted `useMessages()` state. Handle `liveItems`, `turnSources`, completion, Stop, retries and queued messages; a persisted message list alone cannot render the live response.

Declare `richReplies`, `structuredQuestions` or `pageEffects` only after implementing the interaction, including history and consent where applicable. The standard widget declares support for its built-in renderers. Custom replacements must declare their own support.

Existing custom action-result components are separate from the rich-reply catalog. Widget 5.0.0 does not add a customer-defined component catalog or generic rich-reply forms. Personal-connection forms are a separate supported flow.

## Team replies and quoted messages

AI and teammate replies can include `replyTo`. Custom message renderers should preserve the quoted sender and handle a missing quoted message after a partial history load. Companion's `bubbles` and `avatars` are independent; omitted `avatars` follows `bubbles`.

## Keep page context intentional

A `context` object or callback is host-supplied data. It still accompanies messages when automatic page collection is off. Remove or narrow it separately if the data should not be transmitted. `messageCustomData` and `sessionCustomData` are for your team and are separate from agent context.

Use a callback that reads current application state. Strip URL query strings and fragments, and omit private path or title data. Mark sensitive page regions with `data-opencx-private` to exclude them from widget-collected page context. That attribute cannot sanitize data you explicitly supply through another field.

Give interactive controls an accessible name through a visible associated label or `aria-label`. Unnamed dropdowns are excluded from page controls; option text alone does not name the dropdown. Verify that intended controls appear before testing multi-step actions.

Page actions use the site's normal event handlers after visitor approval. Slow loading, navigation or an interrupted event sequence can produce an uncertain result. Test actual site flows and verify the result before retrying a potentially completed operation.

## Verify before rollout

1. Run your unchanged v4 configuration with the new package. Check branding, header callbacks, contact fields, required starters, RTL, mobile layouts and custom renderers.
2. With streaming off, send messages, upload an attachment, receive AI and human replies, and reload history.
3. Renew a real token for the same user; confirm the session remains. Switch A → B → A and verify each account sees only its own permitted history. Test logout and a resumed browser tab.
4. If using streaming, test Stop, a second message during a reply, retries, human handoff and history after reload.
5. Test Companion layouts independently. If enabling page features, test Allow and No, a clarification followed by an action, account switching during a pending action, and slow multi-step flows.
6. For self-hosting, verify the exact served script and existing open tabs. For connections, check authorization, account isolation and renewed tokens.

For rollback, restore the pinned package versions or script URL and prior options together. Changing an npm tag does not replace a cached script or an already installed package.

[Install the migration skill](/widget/agent-skills) if you want your coding assistant to check the same contract. Ask it to use this guide and an exact published version.


# Mobile Support
Source: https://docs.open.cx/widget/native-mobile

Add OpenCX AI chat to your iOS, Android, or React Native app with a WebView support screen.

Use this page when you want customers to open chat inside your mobile app. These examples target Widget 5.0.0; [check version availability](/widget/install-widget#choose-your-version) before using the pinned script.

<Tip>
  Build one support page, load it in a WebView, and let OpenCX handle the conversation.
</Tip>

<Info>
  Rendering chat with your own React Native components instead of a WebView? Use the [headless packages](/widget/custom-components-headless#stream-in-react-native).
</Info>

## What You Are Building

Add a **Support** screen to your app. That screen opens a WebView pointed at a small HTTPS page with the OpenCX widget already open.

## Implementation Steps

<Steps>
  <Step title="Create a support page">
    Host a page like `https://app.example.com/mobile-support`. Your app will load this URL in a WebView.
  </Step>

  <Step title="Add the widget">
    Give the page a real viewport height. Without this, the widget can load but the chat input may sit too high on the screen.

    ```html support.html theme={"dark"}
    <style>
      html,
      body {
        margin: 0;
        width: 100%;
        height: 100%;
        overflow: hidden;
      }

      #opencx-root {
        width: 100vw;
        height: 100dvh;
      }
    </style>

    <script defer src="https://unpkg.com/@opencx/widget@5.0.0/dist-embed/script.js"></script>
    <script>
      window.addEventListener('DOMContentLoaded', () => {
        initOpenScript({
          token: '<WIDGET_TOKEN>',
          inline: true,
          isOpen: true,
          router: {
            chatScreenOnly: true,
            goToChatIfNoSessions: true,
          },
          theme: {
            screens: {
              chat: {
                width: '100vw',
                height: '100vh',
              },
            },
          },
        });
      });
    </script>
    ```
  </Step>

  <Step title="Open the page from your app">
    Add a Support button, Help Center row, or Account menu item that opens the WebView.
  </Step>

  <Step title="Test the mobile flow">
    Open the app, start a chat, close the screen, reopen it, and confirm the conversation still feels natural.
  </Step>
</Steps>

## Open The WebView

<Tabs>
  <Tab title="React Native">
    Install `react-native-webview` first if your app does not already use it.

    ```tsx SupportScreen.tsx theme={"dark"}
    import { WebView } from 'react-native-webview';

    export function SupportScreen({ supportUrl }: { supportUrl: string }) {
      return (
        <WebView
          source={{ uri: supportUrl }}
          javaScriptEnabled
          domStorageEnabled
          allowsInlineMediaPlayback
        />
      );
    }
    ```
  </Tab>

  <Tab title="iOS">
    ```text SupportViewController.swift theme={"dark"}
    import UIKit
    import WebKit

    final class SupportViewController: UIViewController {
      private let webView = WKWebView()

      override func viewDidLoad() {
        super.viewDidLoad()
        view = webView

        let url = URL(string: "https://app.example.com/mobile-support")!
        webView.load(URLRequest(url: url))
      }
    }
    ```
  </Tab>

  <Tab title="Android">
    ```text SupportActivity.kt theme={"dark"}
    import android.os.Bundle
    import android.webkit.WebView
    import androidx.appcompat.app.AppCompatActivity

    class SupportActivity : AppCompatActivity() {
      override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val webView = WebView(this)
        setContentView(webView)

        webView.settings.javaScriptEnabled = true
        webView.settings.domStorageEnabled = true
        webView.loadUrl("https://app.example.com/mobile-support")
      }
    }
    ```
  </Tab>
</Tabs>

## Recognize Signed-In Customers

If customers sign in to your app, pass a verified contact token to the widget. This lets the same customer see their support history across devices.

<Steps>
  <Step title="Request a token from your backend">
    Your backend calls OpenCX with your org API key. Do not call this from the mobile app.

    ```ts theme={"dark"}
    const response = await fetch('https://api.open.cx/widget/authenticate-user', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.OPENCX_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        email: user.email,
        name: user.name,
        customData: {
          customerId: user.id,
          plan: user.plan,
        },
      }),
    });

    const { token } = await response.json();
    ```
  </Step>

  <Step title="Pass the token into the widget">
    Add the token to your support page config. Your backend can render it into the page or your app can request it before opening the WebView.

    ```js theme={"dark"}
    initOpenScript({
      token: '<WIDGET_TOKEN>',
      inline: true,
      isOpen: true,
      user: {
        token: '<AUTHENTICATED_CONTACT_TOKEN>',
        externalId: '<CURRENT_ACCOUNT_ID>',
      },
    });
    ```
  </Step>
</Steps>

<Warning>
  Never put your OpenCX API key in the mobile app. Keep it on your backend.
</Warning>

## Send Useful Context

Give support enough context to help without asking the customer to repeat themselves.

```js theme={"dark"}
initOpenScript({
  token: '<WIDGET_TOKEN>',
  inline: true,
  isOpen: true,
  context: { screen: 'order-details', orderId: 'ORD-123' },
  sessionCustomData: {
    platform: 'ios',
    appVersion: '8.4.0',
    accountId: 'acct_123',
  },
});
```

Keep this clean. Send account IDs, plan names, app version, and the screen the customer came from. Do not send secrets or device identifiers.

## Handoff and native notifications

Human replies remain in the same widget session. There is no `onHandoff` widget option. `hooks.onMessageReceived` reports new messages and is not an immediate transfer event; do not use it to claim that a transfer has just completed.

For a native banner on a delivered human reply, check `message.type === 'AGENT'` in that hook and send a small event through your WebView bridge. Validate bridge messages and the loaded page origin in your native app. Keep tokens and message content out of bridge events unless your application requires them.

When switching accounts or logging out, update the verified widget identity and clear the previous native account’s state. Renew expiring tokens through your backend; see [JWT renewal](/widget/authentication#renew-identity-without-losing-the-active-session).

## Mobile Checklist

| Check | Why it matters |
| - | - |
| `inline: true` | Makes the widget feel like the screen, not a website popup. |
| `isOpen: true` | Opens chat immediately. |
| `router.chatScreenOnly` | Skips the website-style session browser. |
| Verified `user.token` | Keeps signed-in customers tied to the right contact. |
| Server-side API key | Keeps your OpenCX credentials out of the app bundle. |

***

## Related Documentation

<CardGroup>
  <Card title="Install Widget" icon="plug" href="/widget/install-widget">
    Web, React, and headless install paths.
  </Card>

  <Card title="Authentication" icon="shield-check" href="/widget/authentication">
    Verified contact tokens and history access.
  </Card>

  <Card title="Configuration" icon="gear" href="/widget/configuration">
    Inline mode, routing, theme, and context options.
  </Card>

  <Card title="Headless" icon="code" href="/widget/custom-components-headless">
    Build custom rendering when WebView is not enough.
  </Card>
</CardGroup>


# Playground
Source: https://docs.open.cx/widget/playground

Tweak widget options in a live form and copy the generated code. No install required.

Tweak the options in the right-hand panel and watch the snippet update. Hit **Launch preview** to load the widget live with your current settings.

To require a question before typing, add at least one question under **First visit**, then turn on **Require an initial question**. The preview hides the message box until you select a question, and the generated snippet includes `requireInitialQuestion: true`.

<Note>
  This playground previews Widget `4.0.63` and generates HTML snippets pinned to that version. For the generated React snippet, install `@opencx/widget-react@4.0.63` separately. Widget `5.0.0` also supports required starters; Companion keeps a disabled composer beneath them. To test v5 layout, streaming and page permissions, use the [Companion setup](/widget/companion-mode) with a published v5 build.
</Note>

<div>
  <div>
    <iframe title="Widget preview" />

    <iframe title="Widget snippet" />
  </div>

  <iframe title="Widget options" />
</div>

<Tip>
  The preview uses a shared demo workspace so you can try everything without signing up. Replace the `token` in the generated snippet with your own (dashboard → **Channels → Chat Widget**) before shipping.
</Tip>

## What You Can Tweak Here

<CardGroup>
  <Card title="Identity" icon="id-card">
    Bot name, avatar, and language.
  </Card>

  <Card title="Theme" icon="paintbrush">
    Primary color, palette, border radius, launcher size and position.
  </Card>

  <Card title="First visit" icon="hand-wave">
    Initial messages, suggested questions, and requiring a question before typing.
  </Card>

  <Card title="Behavior" icon="sliders">
    Open-by-default, auto-open delay, visitor data collection, single-session mode.
  </Card>
</CardGroup>

## Need Something More Advanced?

The playground covers the options most sites need. For deeper control — custom components, CSS overrides, header buttons, or programmatic hooks — head to the code-based references:

<CardGroup>
  <Card title="Configuration" icon="gear" href="/widget/configuration">
    Full option reference with every field and its defaults.
  </Card>

  <Card title="Custom React Components" icon="react" href="/widget/custom-components-react">
    Render AI action results as typed React components.
  </Card>

  <Card title="Headless" icon="code" href="/widget/custom-components-headless">
    Build fully custom chat UI with the headless package.
  </Card>

  <Card title="Install the widget" icon="download" href="/widget/install-widget">
    Script tag, React package, or headless — pick your integration.
  </Card>
</CardGroup>


# Widget troubleshooting
Source: https://docs.open.cx/widget/troubleshooting

Fix common AI Chat Widget issues such as a missing embed, repeated identity prompts, missing history, and custom component failures.

Before debugging, have these ready: the page where the widget is embedded, the widget mode you are using (HTML, React, or headless), the identity model you chose, and one recent conversation if possible.

<Tip>
  Looking for setup guidance? See [Install Widget](/widget/install-widget), [Mobile Support](/widget/native-mobile), [Authentication](/widget/authentication), and [Conversation Sessions](/widget/conversation-sessions).
</Tip>

<Info>
  Can't reproduce a styling or option issue locally? Open the **[Playground](/widget/playground)** to run the widget in isolation with a known-good config and compare behavior.
</Info>

## Common Troubleshooting Scenarios

| Symptom | Likely cause | What to do |
| - | - | - |
| **Widget does not appear** | Missing script, wrong widget token, or the widget is mounted in the wrong place | Re-check the embed snippet, confirm the widget token from your [OpenCX dashboard](https://platform.open.cx/channels/configure/widget), and verify whether you intended a floating or inline embed. |
| **Visitor is asked for details again or cannot see earlier chats** | The widget is using an anonymous or non-verified identity, or browser storage was reset | Decide whether the visitor should stay anonymous, use `collectUserData`, or receive a verified `user.token`. If history must work across devices, use server-side authentication. |
| **Signed-in customer still cannot see the right history** | The widget is using `user.data` instead of `user.token`, or history should be scoped with `externalId` | Verify that your backend is calling `/widget/authenticate-user`, then pass the returned token as `user.token`. If the same email can belong to multiple accounts, add `externalId`. |
| **Custom action result shows as plain text instead of your UI** | The component key does not match the action `operation_id`, or your headless renderer is not branching on the right action name | Re-check the component mapping, confirm the action name, and make sure your component has a fallback state for missing payload data. |

<Info>
  Most widget issues come from one of three places: the [embed path](/widget/install-widget), the [visitor identity model](/widget/authentication), or [custom rendering logic](/widget/custom-components). Start there before assuming the problem is in the AI itself.
</Info>

## Identity And History Checklist

Work through these in order if history is the problem:

1. **Check whether the visitor is anonymous, non-verified, or verified.**
2. **Confirm whether your app is passing `user.data` or `user.token`.**
3. **Decide whether cross-device history is actually required.**
4. **Add `externalId` if one person can belong to multiple accounts or workspaces.**
5. **Retest with the same browser and then with a second device.**

## Personal Connections And Approvals

| Symptom | What to check |
| - | - |
| **Connect is unavailable** | Supply a valid `user.token` issued with explicit `mcp_access` (use `{}` for all personal servers), enable the server for per-user access, and check that `mcp_access.server_ids` does not exclude it. Omitting the list allows all enabled per-user servers; an empty list allows none. Check that `capabilities.connections` is not `false`. |
| **Authorization page does not open** | Allow the connection popup and try Connect again. A blocked popup does not complete authorization. |
| **Returned from setup but the tool still needs access** | For a customer-managed gateway, returning triggers a tool retry. The gateway must verify that setup completed for the signed user/account. |
| **Approval form expired** | Requests wait up to 50 seconds. An expired request cancels without approval; ask the agent to try again for a fresh form. |
| **The agent no longer asks for approval** | Open **Connections**, select the service, then use **Saved approvals → Remove approval**. This keeps the service connected and restores prompts for that request. |
| **A new session still has access** | Connections and saved approvals belong to the signed user/account and persist across sessions. Use **Disconnect** to remove personal access. |

See [Authentication](/widget/authentication#connect-each-customers-account) for setup and account isolation.

## After upgrading to v5

| Symptom | Check |
| - | - |
| Replies arrive all at once | `streaming` is omitted or false, the organization has streaming disabled, or `presentation.streaming` is false. Layout and agent version do not opt an embed into streaming. |
| Connection controls are missing | Enable `capabilities.connections: true` and streaming, and use a verified token with the required `mcp_access` scope. |
| The agent cannot see or act on the page | Check organization settings and `features.pageContext`, `features.clientTools` and `features.pageActions`. Actions need all three, streaming and visitor approval. Send a new message after changing permissions so it has fresh page context. |
| Starter questions block typing | `requireInitialQuestion: true` requires a choice in a new session. Companion shows a disabled composer; the popover hides it. |
| Headless provider throws about components | Pass a nonempty `components` array with a `fallback` renderer. It is required even when your own transcript does not use the registry. |
| Session resets when refreshing a token | Keep the signed owner, account, widget token and `externalId` consistent. Use the OpenCX-issued contact token. Identity changes intentionally reset active state. |
| A custom transfer callback never runs | `onHandoff` is not a supported widget option. A new-message callback is not an immediate handoff signal. |
| Self-hosted v5 requests a missing `widget.js` | That is an earlier split beta build. Widget 5.0.0 provides a self-contained `dist-embed/script.js`; check the actual served version and cached assets. |

## Expectations And Limits

| Area | Detail |
| - | - |
| **Returning history** | Newest conversations appear first when history is available for that identity. |
| **Resolved sessions** | Resolved sessions remain in history, but they are not active chat threads. |
| **File uploads** | Files larger than **5 MB** are rejected. |
| **Custom UI** | If your custom renderer does not match the action name or payload, the widget falls back to normal message rendering or your own fallback logic. |

***

## Related Documentation

<CardGroup>
  <Card title="Install Widget" icon="plug" href="/widget/install-widget">
    Re-check your embed path, token, and launcher mode.
  </Card>

  <Card title="Authentication" icon="shield-check" href="/widget/authentication">
    Fix identity mismatches and cross-device history problems.
  </Card>

  <Card title="Conversation Sessions" icon="route" href="/widget/conversation-sessions">
    Re-check how history, resolution, and handoff should behave.
  </Card>

  <Card title="Mobile Support" icon="phone" href="/widget/native-mobile">
    Re-check WebView, identity, and mobile support setup.
  </Card>
</CardGroup>