{ "openapi": "3.1.0", "info": { "title": "Chatway Developer Docs", "version": "1.0.0", "description": "# Overview\n\nWelcome to the Chatway developer docs. Use these pages to integrate Chatway into your product with the REST API and outbound webhooks.\n\n## What's in these docs\n\n- **Getting Started** \u2014 Create an API key, send your first request, and learn about testing, rate limits, errors, and support.\n- **API Reference** \u2014 Browse every REST endpoint with request and response schemas. Use **Try It** to send live requests from the browser.\n- **Webhook docs** \u2014 Subscribe to real-time events such as new messages, conversation updates, and contact changes.\n\nIf you are new to Chatway, start with **Quickstart**. If you already have an API key, jump to any endpoint in the sidebar.\n\n## REST API\n\nThe Chatway REST API lets you read and update Chatway data programmatically using standard HTTP methods and JSON.\n\nThe Chatway REST API is available on all plans, including the Free plan.\n\n### Base URL\n\n```\nhttps:\/\/developers.chatway.app\/api\/v1\n```\n\n### Authentication\n\nAll endpoints require an API key in the `X-API-KEY` header. See **Quickstart** for key creation and your first request.\n\n### Response format\n\nSuccessful responses return JSON. List endpoints are paginated with `page` and `limit` query parameters. See **Pagination** for defaults, limits, response shape, and sort order.\n\nErrors use conventional HTTP status codes with a JSON `message` field. Validation failures include an `errors` object. See **Errors** for response bodies, `401` vs `403`, and `429` \/ `Retry-After` behavior.\n\n## Resources\n\n| Tag | What you can do |\n|---|---|\n| **Widgets** | List chat widgets in your workspace. |\n| **Contacts** | List, retrieve, update, and initialize visitor contacts. |\n| **Conversations** | List conversations, read messages, and resolve conversations. |\n| **Messages** | Send new messages into a conversation. |\n| **Agents** | List agents, retrieve agent details, and invite new agents. |\n\nSelect a tag in the sidebar to see every operation, request schema, and response example.\n\n## Real-time events\n\nFor push notifications when something happens in Chatway (new messages, conversation updates, and more), use **Webhook docs** in the sidebar instead of polling these endpoints.\n\nThe most common pattern is documented step-by-step in **Quickstart \u2192 Receive a message and send a reply**: subscribe to `message.received`, read `data.conversation.id` from the webhook, and call **POST \/messages** to reply.\n\n## Next steps\n\n- **Quickstart**: account, API key, and first request.\n- **Pagination**: list endpoints, page sizes, and sort order.\n- **Errors**: response bodies and status code reference.\n- **Testing the API**: Try It, curl, and webhook testing tips.\n- **Rate limits**: per-key limits and retry behavior.\n" }, "servers": [ { "url": "https:\/\/developers.chatway.app\/api\/v1", "description": "Live Server" } ], "tags": [ { "name": "Quickstart" }, { "name": "Testing the API" }, { "name": "Rate limits" }, { "name": "Errors" }, { "name": "Customer support" }, { "name": "Overview", "description": "REST API overview" }, { "name": "Pagination", "description": "List endpoint pagination" }, { "name": "Webhooks overview", "description": "Outbound webhook overview" }, { "name": "ChatContact", "description": "Contact endpoints" }, { "name": "Agent", "description": "Agent endpoints" }, { "name": "Widgets", "description": "Widget endpoints" }, { "name": "Contacts", "description": "Chat contacts" }, { "name": "Conversations", "description": "Conversations" }, { "name": "Messages", "description": "Messages" }, { "name": "Agents", "description": "Team agents" } ], "security": [ { "tenant": [] } ], "paths": { "\/guides\/quickstart": { "get": { "operationId": "guides.quickstart", "description": "# Quickstart\n\nGet started with the Chatway API in just a few steps.\n\nChatway is a customer support and live chat platform that helps businesses communicate with website visitors, manage conversations, automate support with AI, and keep customer interactions in one place.\n\nWith the Chatway API, you can connect Chatway to your own apps, systems, and AI agents to access conversation data, manage contacts, send and reply to messages, and build custom workflows or integrations.\n\nWith webhooks, Chatway can automatically notify your system when important events happen, such as when a new message is received, so you can trigger automations, sync data, or connect Chatway with external services in real time.\n\nThe Chatway API and Webhooks are available on all plans, including the Free plan.\n\n## 1. Create a Chatway account\n\nTo use the Chatway API, you first need a Chatway account.\n\nIf you don't have one yet, create an account and set up your Chatway workspace.\n\n## 2. Generate an API key\n\nIn your Chatway dashboard, go to:\n\n```\nSettings \u2192 Developer Tools \u2192 API Keys\n```\n\nGive your API key a name, generate it, and copy it somewhere secure.\n\nYour full API key is only shown once, so make sure to save it when it is created.\n\n## 3. Authenticate your requests\n\nInclude your API key in the `X-API-KEY` header with every request:\n\n```\nX-API-KEY: your_api_key\n```\n\nKeep your API key private and never expose it in client-side code or public repositories.\n\n## 4. Send your first request\n\nAll API requests use the following base URL:\n\n```\nhttps:\/\/developers.chatway.app\/api\/v1\n```\n\nConfirm your key works with a simple read-only request:\n\n```bash\ncurl -X GET \"https:\/\/developers.chatway.app\/api\/v1\/widgets\" \\\n -H \"X-API-KEY: your_api_key\" \\\n -H \"Accept: application\/json\"\n```\n\nIf authentication is successful, Chatway returns `200` with JSON data.\n\n## 5. Set up webhooks\n\nWebhooks notify your application when something happens in Chatway, so you do not need to poll the API for new messages.\n\n1. In your Chatway dashboard, go to **Settings \u2192 Developer Tools \u2192 Webhooks**.\n2. Add an **HTTPS** endpoint URL that your server controls.\n3. Copy the webhook **secret** when it is shown. You need it to verify signatures.\n4. Subscribe to **`message.received`** (and any other events you need).\n\nWhen an event occurs, Chatway sends an HTTP **POST** to your URL with a signed JSON envelope. Return any **2xx** status within the timeout to acknowledge delivery.\n\nFor signature verification, retries, and header reference, see **Webhook docs \u2192 Overview** in the sidebar.\n\n## 6. Receive a message and send a reply\n\nThis is the most common integration path: a visitor sends a chat message, your server receives a webhook, and you reply through the API.\n\n```\nVisitor message \u2192 message.received webhook \u2192 your server \u2192 POST \/messages reply\n```\n\n### Step A: Receive `message.received`\n\nWhen a visitor sends a message, Chatway POSTs a payload like this:\n\n```json\n{\n \"id\": \"evt_1234567890abcdef1234567890abcdef\",\n \"event\": \"message.received\",\n \"occurred_at\": \"2026-02-04T10:31:12Z\",\n \"version\": \"1.0\",\n \"data\": {\n \"message\": {\n \"id\": \"msg_789\",\n \"content\": \"Hello, I need help\",\n \"attachments\": [],\n \"created_at\": \"2026-02-04T10:31:12Z\"\n },\n \"conversation\": {\n \"id\": \"0f46c0a1-8938-40e3-b2b5-bb56f569fcab\",\n \"channel\": \"website\",\n \"status\": \"open\",\n \"widget_name\": \"Main site widget\",\n \"identifier\": \"wdg_abc123\"\n },\n \"visitor\": {\n \"id\": \"vis_456\",\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"phone\": null\n }\n }\n}\n```\n\nVerify the request signature before processing. See **Webhook docs \u2192 Overview \u2192 Signature verification**.\n\n### Step B: Extract the IDs you need\n\n| Webhook field | Use it for |\n|---|---|\n| `data.conversation.id` | **`conversation_id`** when calling `POST \/messages` (required) |\n| `data.message.id` | Deduplication, logging, or linking to the inbound message |\n| `data.visitor.id` | The visitor\/contact ID (`visitor` in webhooks = **contact** in the REST API) |\n\nYou do **not** need to call `GET \/conversations\/all` first if you already have `data.conversation.id` from the webhook.\n\n### Step C: Send the reply\n\nCall **POST \/messages** with the conversation ID from the webhook:\n\n```bash\ncurl -X POST \"https:\/\/developers.chatway.app\/api\/v1\/messages\" \\\n -H \"X-API-KEY: your_api_key\" \\\n -H \"Content-Type: application\/json\" \\\n -d '{\n \"conversation_id\": \"0f46c0a1-8938-40e3-b2b5-bb56f569fcab\",\n \"content\": \"Thanks for reaching out! How can I help?\"\n }'\n```\n\nTo send the reply **as a specific team member**, include `agent_id` from `GET \/agents`:\n\n```bash\ncurl -X POST \"https:\/\/developers.chatway.app\/api\/v1\/messages\" \\\n -H \"X-API-KEY: your_api_key\" \\\n -H \"Content-Type: application\/json\" \\\n -d '{\n \"conversation_id\": \"0f46c0a1-8938-40e3-b2b5-bb56f569fcab\",\n \"agent_id\": \"26fa75f2-7ac1-47b4-84e1-b943491ba4da\",\n \"content\": \"Thanks for reaching out! How can I help?\"\n }'\n```\n\nA successful reply returns **201** with the created message. See **API Reference \u2192 Messages \u2192 Create Message** for all request fields.\n\n### Step D: Test locally before production\n\n1. Expose a temporary HTTPS URL (for example [ngrok](https:\/\/ngrok.com\/) or [webhook.site](https:\/\/webhook.site\/)).\n2. Register it under **Settings \u2192 Developer Tools \u2192 Webhooks** and subscribe to **`message.received`**.\n3. Send a test visitor message in your Chatway widget.\n4. Confirm your endpoint receives the webhook and your `POST \/messages` call returns **201**.\n\nSee **Testing the API** for a full smoke-test checklist.\n\n## 7. Handle errors and rate limits\n\nChatway uses standard HTTP status codes with JSON bodies. For example:\n\n| Code | Meaning |\n|---|---|\n| 200 | Request successful |\n| 201 | Resource created successfully |\n| 401 | Missing or invalid API key |\n| 403 | Valid key, but API access not allowed for this account |\n| 404 | Resource not found |\n| 422 | Validation error (see `errors` object in the body) |\n| 429 | Rate limit exceeded |\n\nExample validation response:\n\n```json\n{\n \"message\": \"The limit must be an integer.\",\n \"errors\": {\n \"limit\": [\n \"The limit must be an integer.\"\n ]\n }\n}\n```\n\nThe API allows **60 requests per minute** per API key. A `429` response includes a `Retry-After` header when available.\n\nSee **Errors** and **Rate limits** in the sidebar for full response examples and retry guidance.\n\n## What to read next\n\n| Goal | Page |\n|---|---|\n| Try endpoints in the browser | **Testing the API** |\n| Browse every endpoint and schema | **API Reference** |\n| List pagination and sort order | **Pagination** |\n| Error response bodies | **Errors** |\n| Webhook signatures, retries, all events | **Webhook docs \u2192 Overview** |\n| Get help from Chatway | **Customer support** |\n", "summary": "Quickstart", "tags": [ "Quickstart" ], "responses": { "200": { "description": "Documentation." } }, "security": [] } }, "\/guides\/testing-the-api": { "get": { "operationId": "guides.testing_the_api", "description": "# Testing the API\n\nUse these approaches to explore the Chatway API safely before wiring it into production.\n\n## Try It in the docs\n\nEach endpoint under **API Reference** includes a **Try It** panel. Enter your API key in the **Auth** section (`X-API-KEY`), fill in any path or query parameters, and send the request directly from the browser.\n\nTry It sends requests to the same base URL shown in the docs server selector, so you can confirm authentication, request shape, and response structure without writing code first.\n\n> Use a dedicated test API key with the minimum access you need. Rotate or revoke the key when you finish experimenting.\n\n## Test with curl\n\nCopy any endpoint example and run it from your terminal:\n\n```bash\ncurl -X GET \"https:\/\/developers.chatway.app\/api\/v1\/contacts\" \\\n -H \"X-API-KEY: your_api_key\" \\\n -H \"Accept: application\/json\"\n```\n\nReplace method, path, and body to match the operation you are testing. A `401` usually means a missing or invalid key; `422` means the payload or query string failed validation.\n\n## Confirm authentication\n\nRun a simple read-only call such as `GET \/contacts` or `GET \/widgets`:\n\n- **200**: key is valid and the request succeeded.\n- **401**: key is missing, malformed, or revoked.\n- **403**: key is valid but the requested action is not permitted for this account or resource.\n\n## Test write operations carefully\n\nBefore calling endpoints that create or update data (`POST \/messages`, `POST \/contacts\/initialize`, `POST \/conversations\/{id}\/resolve`, and similar):\n\n1. Note the resource IDs returned by list endpoints.\n2. Send the smallest valid payload from the schema example.\n3. Re-fetch the resource to confirm the change.\n\n## Test webhooks locally\n\nWebhooks are delivered **to your server**, not to the Chatway API. To test the full receive-and-reply flow locally:\n\n1. Expose a temporary HTTPS URL with a tunnel (for example [ngrok](https:\/\/ngrok.com\/) or [webhook.site](https:\/\/webhook.site\/)).\n2. Register that URL under **Settings \u2192 Developer Tools \u2192 Webhooks** and subscribe to **`message.received`**.\n3. Send a test visitor message in your Chatway widget.\n4. Verify your endpoint receives the signed JSON envelope and returns a `2xx` response within the timeout.\n5. Reply using `POST \/messages` with `conversation_id` from `data.conversation.id` in the webhook (see **Quickstart \u2192 Receive a message and send a reply**).\n\nSee **Webhook docs \u2192 Overview** for header and signature verification details.\n\n## Suggested smoke-test checklist\n\n| Step | Request | Expected |\n|---|---|---|\n| Auth | `GET \/widgets` with `X-API-KEY` | `200` and widget list |\n| Reply flow | Receive `message.received`, then `POST \/messages` with `data.conversation.id` | Webhook `2xx`, reply `201` |\n| Contacts | `GET \/contacts` | `200` and paginated contacts |\n| Conversations | `GET \/conversations\/all` | `200` and conversation list |\n| Messages | `GET \/conversations\/{id}\/messages` | `200` for a valid conversation ID |\n| Rate limit | Repeat the same request rapidly | Eventually `429` if you exceed the per-key limit |\n\n## When something fails\n\nCapture the HTTP status, response body, UTC timestamp, and the exact method + path. See **Customer support** if you need help from the Chatway team.\n", "summary": "Testing the API", "tags": [ "Testing the API" ], "responses": { "200": { "description": "Documentation." } }, "security": [] } }, "\/guides\/rate-limits": { "get": { "operationId": "guides.rate_limits", "description": "# Rate limits\n\nThe Chatway API enforces per-key rate limits to keep the platform stable for all customers.\n\n## Limits\n\n| Limit | Window | Scope |\n|---|---|---|\n| **60 requests** | Per minute | Per API key |\n\nEvery authenticated API request counts toward the limit for the key used in the `X-API-KEY` header.\n\n## When you exceed the limit\n\nRequests over the limit receive:\n\n```\nHTTP\/1.1 429 Too Many Requests\n```\n\nThe response body includes a JSON error message. When provided, honor the **`Retry-After`** header (seconds until you should retry).\n\nExample response:\n\n```json\n{\n \"message\": \"Too many requests.\"\n}\n```\n\nThe response may include a **`Retry-After`** header (seconds until you should retry).\n\n## Recommended client behavior\n\n1. **Backoff**: wait at least `Retry-After` seconds before retrying the same request.\n2. **Jitter**: add a small random delay when many workers share one key to avoid retry storms.\n3. **Cache reads**: store list results locally when polling; prefer webhooks for near-real-time updates instead of tight polling loops.\n4. **Separate keys**: use different API keys for production and background jobs so one integration cannot exhaust another's quota.\n\n## Webhooks vs polling\n\nWebhook deliveries are separate from REST API rate limits. Design integrations to react to webhook events rather than calling list endpoints on a short interval.\n\n## Related pages\n\n- **Testing the API**: safe ways to exercise endpoints without hitting limits unexpectedly.\n- **Errors**: full error body reference, including `429` and `Retry-After`.\n- **Customer support**: include timestamps and paths if you believe a limit was applied incorrectly.\n", "summary": "Rate limits", "tags": [ "Rate limits" ], "responses": { "200": { "description": "Documentation." } }, "security": [] } }, "\/guides\/errors": { "get": { "operationId": "guides.errors", "description": "# Errors\n\nAll Chatway REST API errors return JSON with a `message` field. Validation failures also include an `errors` object with field-specific messages.\n\nThere is **no request or trace ID** in error responses today. When contacting support, include the UTC timestamp, HTTP method, path, status code, and full response body.\n\n## Response shape\n\n### Standard error\n\nMost errors use this shape:\n\n```json\n{\n \"message\": \"Conversation not found\"\n}\n```\n\n### Validation error (`422`)\n\nWhen query or body parameters fail validation:\n\n```json\n{\n \"message\": \"The limit must be an integer.\",\n \"errors\": {\n \"limit\": [\n \"The limit must be an integer.\"\n ]\n }\n}\n```\n\nMultiple fields may appear under `errors`. The top-level `message` is usually the first validation failure.\n\n## Status codes\n\n### `401 Unauthorized`\n\n**Meaning:** the request is not authenticated.\n\nCommon causes:\n\n- Missing `X-API-KEY` header\n- Invalid or revoked API key\n\nExample:\n\n```json\n{\n \"message\": \"Unauthenticated.\"\n}\n```\n\n**What to do:** create or rotate a key under **Settings \u2192 Developer Tools \u2192 API Keys** and send it in `X-API-KEY`.\n\n### `403 Forbidden`\n\n**Meaning:** the request was authenticated, but the key is not allowed to perform this action (for example, the resource belongs to another workspace).\n\n**401 vs 403:** use **401** when the key is missing or not recognized. Use **403** when the key is valid but the action is not permitted.\n\n### `404 Not Found`\n\n**Meaning:** the route or resource does not exist for your workspace.\n\nExamples:\n\n```json\n{\n \"message\": \"Conversation not found\"\n}\n```\n\n```json\n{\n \"message\": \"Resource not found.\"\n}\n```\n\n```json\n{\n \"message\": \"Not found.\"\n}\n```\n\n**What to do:** confirm the ID (from a webhook payload or a list endpoint), that the resource belongs to your workspace, and that the path is correct.\n\n### `422 Unprocessable Entity`\n\n**Meaning:** validation failed on query parameters or JSON body.\n\nSee [Validation error](#validation-error-422) above.\n\nCommon cases:\n\n- `limit` above the maximum for that endpoint\n- Missing required body fields (for example `conversation_id` on `POST \/messages`)\n- Invalid field filter names in `include_fields` or `exclude_fields`\n\n### `429 Too Many Requests`\n\n**Meaning:** rate limit exceeded for your API key.\n\nBody:\n\n```json\n{\n \"message\": \"Too many requests.\"\n}\n```\n\nResponse headers:\n\n| Header | Description |\n|---|---|\n| `Retry-After` | Seconds to wait before retrying (when provided by the rate limiter) |\n\nThe public API allows **60 requests per minute** per API key. See **Rate limits** for backoff guidance.\n\n### `500 Internal Server Error`\n\n**Meaning:** an unexpected server error.\n\nExample:\n\n```json\n{\n \"message\": \"Server Error\"\n}\n```\n\n**What to do:** retry with backoff. If the error persists, contact support with the details listed at the top of this page.\n\n## Related pages\n\n- **Rate limits**: per-key limits and retry behavior\n- **Customer support**: what to send when you need help\n- **Quickstart**: authentication and first request\n", "summary": "Errors", "tags": [ "Errors" ], "responses": { "200": { "description": "Documentation." } }, "security": [] } }, "\/guides\/customer-support": { "get": { "operationId": "guides.customer_support", "description": "# Customer support\n\nIf you need help with the Chatway API, webhooks, or your integration, visit our [Help Center](https:\/\/chatway.app\/help).\n\nYou can also contact the Chatway support team directly through live chat on the Help Center or Chatway website. Our team can help with API errors, authentication, webhook setup, unexpected responses, and other integration questions.\n\n## Before you write\n\nMost issues resolve faster after a quick pass through the docs. Check the pages most relevant to your problem:\n\n| Symptom | Start here |\n|---|---|\n| Auth errors (`401` \/ `403`) | **Quickstart**: confirm your key was created under **Settings \u2192 Developer Tools \u2192 API Keys** on the correct account. |\n| `429 Too Many Requests` | **Rate limits** and **Errors** for body format and `Retry-After` guidance. |\n| Endpoint behavior, parameters, or response shape | The operation's page under **API Reference**. That page is the source of truth. |\n| Webhook signature, retries, or payload shape | **Webhook docs \u2192 Overview** and the specific event page. |\n| Experimenting safely | **Testing the API**. |\n\nIf your question is still unanswered, gather the details below and contact our support team through live chat at [chatway.app\/help](https:\/\/chatway.app\/help).\n\n## What to include\n\nSupport can diagnose issues faster when you send:\n\n- **UTC timestamp** of the request, or a tight time window if you ran a batch.\n- **HTTP method and path**, for example `POST \/contacts\/initialize`.\n- **Response status and message**, including the HTTP status code and any error body returned. For `422` responses, include the full `errors` object.\n- **Account context**, such as the workspace the API key belongs to, if safe to share.\n- **What you expected vs. what happened**: usually one or two sentences is enough.\n\n> **No trace ID.** Error responses do not currently include a request or trace ID. Send the UTC timestamp, method, path, and response body instead.\n\n> **Redact secrets.** Never share a full API key in live chat, screenshots, emails, support requests, or public threads.\n", "summary": "Customer support", "tags": [ "Customer support" ], "responses": { "200": { "description": "Documentation." } }, "security": [] } }, "\/guides\/api-overview": { "get": { "operationId": "guides.api_overview", "description": "# Overview\n\nWelcome to the Chatway developer docs. Use these pages to integrate Chatway into your product with the REST API and outbound webhooks.\n\n## What's in these docs\n\n- **Getting Started** \u2014 Create an API key, send your first request, and learn about testing, rate limits, errors, and support.\n- **API Reference** \u2014 Browse every REST endpoint with request and response schemas. Use **Try It** to send live requests from the browser.\n- **Webhook docs** \u2014 Subscribe to real-time events such as new messages, conversation updates, and contact changes.\n\nIf you are new to Chatway, start with **Quickstart**. If you already have an API key, jump to any endpoint in the sidebar.\n\n## REST API\n\nThe Chatway REST API lets you read and update Chatway data programmatically using standard HTTP methods and JSON.\n\nThe Chatway REST API is available on all plans, including the Free plan.\n\n### Base URL\n\n```\nhttps:\/\/developers.chatway.app\/api\/v1\n```\n\n### Authentication\n\nAll endpoints require an API key in the `X-API-KEY` header. See **Quickstart** for key creation and your first request.\n\n### Response format\n\nSuccessful responses return JSON. List endpoints are paginated with `page` and `limit` query parameters. See **Pagination** for defaults, limits, response shape, and sort order.\n\nErrors use conventional HTTP status codes with a JSON `message` field. Validation failures include an `errors` object. See **Errors** for response bodies, `401` vs `403`, and `429` \/ `Retry-After` behavior.\n\n## Resources\n\n| Tag | What you can do |\n|---|---|\n| **Widgets** | List chat widgets in your workspace. |\n| **Contacts** | List, retrieve, update, and initialize visitor contacts. |\n| **Conversations** | List conversations, read messages, and resolve conversations. |\n| **Messages** | Send new messages into a conversation. |\n| **Agents** | List agents, retrieve agent details, and invite new agents. |\n\nSelect a tag in the sidebar to see every operation, request schema, and response example.\n\n## Real-time events\n\nFor push notifications when something happens in Chatway (new messages, conversation updates, and more), use **Webhook docs** in the sidebar instead of polling these endpoints.\n\nThe most common pattern is documented step-by-step in **Quickstart \u2192 Receive a message and send a reply**: subscribe to `message.received`, read `data.conversation.id` from the webhook, and call **POST \/messages** to reply.\n\n## Next steps\n\n- **Quickstart**: account, API key, and first request.\n- **Pagination**: list endpoints, page sizes, and sort order.\n- **Errors**: response bodies and status code reference.\n- **Testing the API**: Try It, curl, and webhook testing tips.\n- **Rate limits**: per-key limits and retry behavior.\n", "summary": "Overview", "tags": [ "Overview" ], "responses": { "200": { "description": "Documentation." } }, "security": [] } }, "\/guides\/pagination": { "get": { "operationId": "guides.pagination", "description": "# Pagination\n\nList endpoints use **offset pagination** with `page` and `limit` query parameters. Chatway does **not** use cursor-based pagination (`cursor`, `next_cursor`, or `has_more`).\n\n## Query parameters\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `page` | integer | `1` | Page number (1-based). Must be at least `1`. |\n| `limit` | integer | varies | Number of records per page. Must be at least `1`. Maximum depends on the endpoint (see below). |\n\nExample:\n\n```bash\ncurl -G \"https:\/\/developers.chatway.app\/api\/v1\/contacts\" \\\n -H \"X-API-KEY: your_api_key\" \\\n --data-urlencode \"page=2\" \\\n --data-urlencode \"limit=25\"\n```\n\n## Response shape\n\nPaginated responses include `data`, `meta.pagination`, and `links`:\n\n```json\n{\n \"data\": [],\n \"meta\": {\n \"pagination\": {\n \"total\": 42,\n \"count\": 10,\n \"per_page\": 10,\n \"current_page\": 2,\n \"total_pages\": 5\n }\n },\n \"links\": {\n \"self\": \"https:\/\/developers.chatway.app\/api\/v1\/contacts?page=2\",\n \"first\": \"https:\/\/developers.chatway.app\/api\/v1\/contacts?page=1\",\n \"next\": \"https:\/\/developers.chatway.app\/api\/v1\/contacts?page=3\",\n \"last\": \"https:\/\/developers.chatway.app\/api\/v1\/contacts?page=5\"\n }\n}\n```\n\n| Field | Description |\n|---|---|\n| `meta.pagination.total` | Total records across all pages |\n| `meta.pagination.count` | Records returned on this page |\n| `meta.pagination.per_page` | Page size used for this response (matches `limit`) |\n| `meta.pagination.current_page` | Current page number |\n| `meta.pagination.total_pages` | Total number of pages |\n| `links.next` | URL for the next page, or `null` on the last page |\n| `links.first` \/ `links.last` | First and last page URLs |\n\nFollow `links.next` until it is `null`, or increment `page` until `current_page >= total_pages`.\n\n## Defaults and limits by endpoint\n\n| Endpoint | Default `limit` | Maximum `limit` |\n|---|---|---|\n| `GET \/contacts` | `10` | `100` |\n| `GET \/conversations\/all` | `10` | `100` |\n| `GET \/conversations\/{id}\/messages` | `20` | `20` |\n| `GET \/widgets` | `20` | `100` |\n| `GET \/agents` | `20` | `100` |\n\nSending `limit` above the maximum returns **422** with an validation error.\n\n## Sort order\n\n| Endpoint | Order |\n|---|---|\n| `GET \/conversations\/all` | Open conversations first, then by most recent message activity (newest first) |\n| `GET \/conversations\/{id}\/messages` | Newest messages first (`sort_number` descending) |\n| `GET \/contacts` | Platform default contact ordering for your workspace |\n| `GET \/widgets` | Platform default widget ordering |\n| `GET \/agents` | Platform default agent ordering |\n\nSort order is not configurable through query parameters on these endpoints.\n\n## Live data and page drift\n\nPagination is a snapshot at request time.\n\n- **Conversation lists** can change order when new messages arrive, because ordering uses latest activity.\n- **Message lists** can gain new rows while you paginate; a new visitor or agent message may appear on page 1 after you already fetched page 2.\n\nFor near-real-time workflows, prefer **webhooks** (`message.received`) instead of polling message or conversation lists on a short interval.\n\n## Field filtering\n\nList endpoints also accept optional `include_fields` and `exclude_fields` query parameters (comma-separated). Invalid field names return **422**. See each endpoint's schema in **API Reference** for allowed fields.\n\n## Related pages\n\n- **Overview**: authentication and resource summary\n- **Errors**: validation and rate-limit responses\n- **Rate limits**: request quotas per API key\n", "summary": "Pagination", "tags": [ "Pagination" ], "responses": { "200": { "description": "Documentation." } }, "security": [] } }, "\/agents": { "get": { "operationId": "api-docs.agents.index", "description": "Retrieve a paginated list of agents. When in mock mode, returns sample agent data.", "summary": "List Agents", "tags": [ "Agents", "Agent" ], "parameters": [ { "name": "email", "in": "query", "schema": { "type": [ "string", "null" ], "format": "email" } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "online_status": { "type": [ "string", "null" ] }, "profile_photo_url": { "type": [ "string", "null" ] }, "resized_profile_photo_url": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] } }, "required": [ "email", "name", "status", "online_status", "profile_photo_url", "resized_profile_photo_url", "role" ] } }, "required": [ "type", "id", "attributes" ] } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "count": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": [ "total", "count", "per_page", "current_page", "total_pages" ] } }, "required": [ "pagination" ] }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "first": { "type": "string" }, "next": { "type": [ "string", "null" ] }, "last": { "type": "string" } }, "required": [ "self", "first", "next", "last" ] } }, "required": [ "data", "meta", "links" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/agents\/{id}": { "get": { "operationId": "api-docs.agents.show", "description": "Retrieve details of a specific agent by ID.", "summary": "Get Agent", "tags": [ "Agents", "Agent" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent ID", "schema": { "type": "string" }, "example": "26fa75f2-7ac1-47b4-84e1-b943491ba4da" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "online_status": { "type": [ "string", "null" ] }, "profile_photo_url": { "type": [ "string", "null" ] }, "resized_profile_photo_url": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] } }, "required": [ "email", "name", "status", "online_status", "profile_photo_url", "resized_profile_photo_url", "role" ] } }, "required": [ "type", "id", "attributes" ] } }, "required": [ "data" ] }, { "type": "object" } ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } } } }, "\/agents\/invite": { "post": { "operationId": "api-docs.agents.store", "description": "Invite one or more agents to the team. Response matches the real API.", "summary": "Invite Agents", "tags": [ "Agents", "Agent" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/InviteAgentRequest" }, { "type": "object", "properties": { "agents": { "type": "array", "description": "Agents to invite", "examples": [ [ { "email": "john@doe.com", "name": "John Doe", "role": "CHAT_AGENT_ADMIN" } ] ], "items": { "type": "string" }, "minItems": 1 } }, "required": [ "agents" ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/.well-known\/agent-skills\/index.json": { "get": { "operationId": "apiDocsAgentSkills.index", "tags": [ "ApiDocsAgentSkills" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "$schema": { "type": "string", "const": "https:\/\/schemas.agentskills.io\/discovery\/0.2.0\/schema.json" }, "skills": { "type": "array", "items": {} } }, "required": [ "$schema", "skills" ] } } }, "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "const": "*" } } } } } } }, "\/.well-known\/agent-skills\/{skill}\/SKILL.md": { "get": { "operationId": "apiDocsAgentSkills.show", "tags": [ "ApiDocsAgentSkills" ], "parameters": [ { "name": "skill", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "text\/markdown; charset=UTF-8": { "schema": { "type": "string" } } }, "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "const": "*" } } } } } } }, "\/.well-known\/api-catalog": { "get": { "operationId": "apiDocs.apiDocsApiCatalog", "tags": [ "ApiDocsApiCatalog" ], "responses": { "200": { "description": "", "content": { "application\/linkset+json": { "schema": { "type": "object", "properties": { "linkset": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "anchor": { "type": "string" }, "service-desc": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "href": { "type": "string" }, "type": { "type": "string", "const": "application\/vnd.oai.openapi+json" } }, "required": [ "href", "type" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "service-doc": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "href": { "type": "string" }, "type": { "type": "string", "const": "text\/html" } }, "required": [ "href", "type" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "status": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "href": { "type": "string" }, "type": { "type": "string", "const": "application\/json" } }, "required": [ "href", "type" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "anchor", "service-desc", "service-doc", "status" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "linkset" ] } } }, "headers": { "Link": { "schema": { "type": "string" } }, "Access-Control-Allow-Origin": { "schema": { "type": "string", "const": "*" } } } } } } }, "\/auth.md": { "get": { "operationId": "apiDocs.apiDocsAuthMd", "tags": [ "ApiDocsAuthMd" ], "responses": { "200": { "description": "", "content": { "text\/markdown; charset=UTF-8": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/.well-known\/{document}": { "get": { "operationId": "apiDocs.apiDocsOAuthMetadata", "tags": [ "ApiDocsOAuthMetadata" ], "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "registration_endpoint": { "type": "string" }, "response_types_supported": { "type": "array", "prefixItems": [ { "type": "string", "const": "code" } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "code_challenge_methods_supported": { "type": "array", "prefixItems": [ { "type": "string", "const": "S256" } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "scopes_supported": { "type": "array", "prefixItems": [ { "type": "string", "const": "mcp:use" } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "grant_types_supported": { "type": "array", "prefixItems": [ { "type": "string", "const": "authorization_code" }, { "type": "string", "const": "refresh_token" } ], "minItems": 2, "maxItems": 2, "additionalItems": false }, "service_documentation": { "type": "string" } }, "required": [ "issuer", "authorization_endpoint", "token_endpoint", "registration_endpoint", "response_types_supported", "code_challenge_methods_supported", "scopes_supported", "grant_types_supported", "service_documentation" ] }, { "type": "object", "properties": { "resource": { "type": "string" }, "resource_name": { "type": "string", "const": "Chatway" }, "resource_documentation": { "type": "string" }, "authorization_servers": { "type": "array", "prefixItems": [ { "type": "string" } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "scopes_supported": { "type": "array", "prefixItems": [ { "type": "string", "const": "mcp:use" } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "bearer_methods_supported": { "type": "array", "prefixItems": [ { "type": "string", "const": "header" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "resource", "resource_name", "resource_documentation", "authorization_servers", "scopes_supported", "bearer_methods_supported" ] } ] } } }, "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string", "const": "*" } } } } } } }, "\/contacts": { "get": { "operationId": "contacts.index", "description": "Retrieve a paginated list of chat contacts. When in mock mode, returns sample contact data.", "summary": "List Chat Contacts", "tags": [ "Contacts", "ChatContact" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "include_fields", "in": "query", "description": "Allowed: widget_name, widget_id, team_id, name, email, phone, country_dialing_code, bgcolor, location, browser_type, country_code, country, country_flag, country_emoji, page_visited, online_status, last_active_at, blocked_at, is_name_updated, created_at, verified_id, verified_email, timezone, language, ip, operating_system. Example: `name,widget_name`. If both this and exclude_fields are sent, only include_fields is applied.", "schema": { "type": [ "string", "null" ] } }, { "name": "exclude_fields", "in": "query", "description": "Allowed: widget_name, widget_id, team_id, name, email, phone, country_dialing_code, bgcolor, location, browser_type, country_code, country, country_flag, country_emoji, page_visited, online_status, last_active_at, blocked_at, is_name_updated, created_at, verified_id, verified_email, timezone, language, ip, operating_system. Ignored when include_fields is also present (include takes precedence).", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "widget_name": { "type": [ "string", "null" ] }, "widget_id": { "type": [ "string", "null" ] }, "team_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "country_dialing_code": { "type": [ "string", "null" ] }, "bgcolor": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "browser_type": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "country_flag": { "type": [ "string", "null" ] }, "country_emoji": { "type": [ "string", "null" ] }, "page_visited": { "type": "array", "items": {} }, "timezone": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "ip": { "type": [ "string", "null" ] }, "operating_system": { "type": [ "string", "null" ] }, "online_status": { "type": [ "string", "null" ] }, "last_active_at": { "type": [ "string", "null" ] }, "blocked_at": { "type": [ "string", "null" ] }, "is_name_updated": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "verified_id": { "type": [ "string", "null" ] }, "verified_email": { "type": [ "string", "null" ] } }, "required": [ "widget_name", "widget_id", "team_id", "name", "email", "phone", "country_dialing_code", "bgcolor", "location", "browser_type", "country_code", "country", "country_flag", "country_emoji", "page_visited", "timezone", "language", "ip", "operating_system", "online_status", "last_active_at", "blocked_at", "is_name_updated", "created_at", "verified_id", "verified_email" ] } }, "required": [ "type", "id", "attributes" ] } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "count": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": [ "total", "count", "per_page", "current_page", "total_pages" ] } }, "required": [ "pagination" ] }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "first": { "type": "string" }, "next": { "type": [ "string", "null" ] }, "last": { "type": "string" } }, "required": [ "self", "first", "next", "last" ] } }, "required": [ "data", "meta", "links" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/contacts\/{id}": { "get": { "operationId": "contacts.show", "description": "Retrieve details of a specific chat contact by ID.", "summary": "Get Chat Contact", "tags": [ "Contacts", "ChatContact" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Chat contact ID", "schema": { "type": "string" }, "example": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "widget_name": { "type": [ "string", "null" ] }, "widget_id": { "type": [ "string", "null" ] }, "team_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "country_dialing_code": { "type": [ "string", "null" ] }, "bgcolor": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "browser_type": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "country_flag": { "type": [ "string", "null" ] }, "country_emoji": { "type": [ "string", "null" ] }, "page_visited": { "type": "array", "items": {} }, "timezone": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "ip": { "type": [ "string", "null" ] }, "operating_system": { "type": [ "string", "null" ] }, "online_status": { "type": [ "string", "null" ] }, "last_active_at": { "type": [ "string", "null" ] }, "blocked_at": { "type": [ "string", "null" ] }, "is_name_updated": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "verified_id": { "type": [ "string", "null" ] }, "verified_email": { "type": [ "string", "null" ] } }, "required": [ "widget_name", "widget_id", "team_id", "name", "email", "phone", "country_dialing_code", "bgcolor", "location", "browser_type", "country_code", "country", "country_flag", "country_emoji", "page_visited", "timezone", "language", "ip", "operating_system", "online_status", "last_active_at", "blocked_at", "is_name_updated", "created_at", "verified_id", "verified_email" ] } }, "required": [ "type", "id", "attributes" ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } }, "put": { "operationId": "contacts.update", "description": "Update the details of an existing chat contact.", "summary": "Update Chat Contact", "tags": [ "Contacts", "ChatContact" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Chat contact ID", "schema": { "type": "string" }, "example": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1" } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateChatContactRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "widget_name": { "type": [ "string", "null" ] }, "widget_id": { "type": [ "string", "null" ] }, "team_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "country_dialing_code": { "type": [ "string", "null" ] }, "bgcolor": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "browser_type": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "country_flag": { "type": [ "string", "null" ] }, "country_emoji": { "type": [ "string", "null" ] }, "page_visited": { "type": "array", "items": {} }, "timezone": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "ip": { "type": [ "string", "null" ] }, "operating_system": { "type": [ "string", "null" ] }, "online_status": { "type": [ "string", "null" ] }, "last_active_at": { "type": [ "string", "null" ] }, "blocked_at": { "type": [ "string", "null" ] }, "is_name_updated": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "verified_id": { "type": [ "string", "null" ] }, "verified_email": { "type": [ "string", "null" ] } }, "required": [ "widget_name", "widget_id", "team_id", "name", "email", "phone", "country_dialing_code", "bgcolor", "location", "browser_type", "country_code", "country", "country_flag", "country_emoji", "page_visited", "timezone", "language", "ip", "operating_system", "online_status", "last_active_at", "blocked_at", "is_name_updated", "created_at", "verified_id", "verified_email" ] } }, "required": [ "type", "id", "attributes" ] } }, "required": [ "message", "data" ] }, { "type": "object" } ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/contacts\/initialize": { "post": { "operationId": "chatContact.initialize", "description": "Create or initialize a new chat contact. This is typically used when a visitor starts a chat.", "summary": "Initialize Chat Contact", "tags": [ "Contacts", "ChatContact" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/StorePublicChatContactRequest" }, { "type": "object", "properties": { "message": { "type": "object", "description": "Optional pre-chat message with referenced page URLs (each URL must be valid)", "examples": [ { "urls": [ "https:\/\/example.com\/page" ], "content": "Hello world" } ] }, "widgetId": { "type": "string", "description": "Widget identifier", "examples": [ "eouqtiupanm6uvglwshy" ] } }, "required": [ "widgetId" ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "widget_name": { "type": [ "string", "null" ] }, "widget_id": { "type": [ "string", "null" ] }, "team_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "country_dialing_code": { "type": [ "string", "null" ] }, "bgcolor": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "browser_type": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "country_flag": { "type": [ "string", "null" ] }, "country_emoji": { "type": [ "string", "null" ] }, "page_visited": { "type": "array", "items": {} }, "timezone": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "ip": { "type": [ "string", "null" ] }, "operating_system": { "type": [ "string", "null" ] }, "online_status": { "type": [ "string", "null" ] }, "last_active_at": { "type": [ "string", "null" ] }, "blocked_at": { "type": [ "string", "null" ] }, "is_name_updated": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "verified_id": { "type": [ "string", "null" ] }, "verified_email": { "type": [ "string", "null" ] } }, "required": [ "widget_name", "widget_id", "team_id", "name", "email", "phone", "country_dialing_code", "bgcolor", "location", "browser_type", "country_code", "country", "country_flag", "country_emoji", "page_visited", "timezone", "language", "ip", "operating_system", "online_status", "last_active_at", "blocked_at", "is_name_updated", "created_at", "verified_id", "verified_email" ] } }, "required": [ "type", "id", "attributes" ] } }, "required": [ "message", "data" ] }, { "type": "object" } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/conversations\/all": { "get": { "operationId": "api-docs.conversations.index", "description": "Retrieve a list of all conversations. In mock mode, returns sample conversation data.", "summary": "List Conversations", "tags": [ "Conversations" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "include_fields", "in": "query", "description": "Allowed: is_resolved, contact_id, unread_messages, latest_message, contact_name, agents, created_at. Example: `contact_name,is_resolved`. If both this and exclude_fields are sent, only include_fields is applied.", "schema": { "type": [ "string", "null" ] } }, { "name": "exclude_fields", "in": "query", "description": "Allowed: is_resolved, contact_id, unread_messages, latest_message, contact_name, agents, created_at. Ignored when include_fields is also present (include takes precedence).", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "is_resolved": { "type": "boolean" }, "contact_id": { "type": "string" }, "unread_messages": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "is_resolved", "contact_id", "unread_messages", "created_at" ] } }, "required": [ "type", "id", "attributes" ] } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "count": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": [ "total", "count", "per_page", "current_page", "total_pages" ] } }, "required": [ "pagination" ] }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "first": { "type": "string" }, "next": { "type": [ "string", "null" ] }, "last": { "type": "string" } }, "required": [ "self", "first", "next", "last" ] } }, "required": [ "data", "meta", "links" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } } } }, "\/conversations\/{conversation_id}\/messages": { "get": { "operationId": "api-docs.conversations.messages", "description": "Retrieve all messages associated with a specific conversation.", "summary": "List Conversation Messages", "tags": [ "Conversations" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "include_fields", "in": "query", "description": "Allowed: conversation_id, chat_contact_id, agent, contact, origin, content, type, created_at. Example: `content,type`. If both this and exclude_fields are sent, only include_fields is applied.", "schema": { "type": [ "string", "null" ] } }, { "name": "exclude_fields", "in": "query", "description": "Allowed: conversation_id, chat_contact_id, agent, contact, origin, content, type, created_at. Ignored when include_fields is also present (include takes precedence).", "schema": { "type": [ "string", "null" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" }, "example": "0f46c0a1-8938-40e3-b2b5-bb56f569fcab" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "origin": { "type": "string" }, "content": { "type": "string" }, "type": { "type": "string" }, "conversation_id": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "origin", "content", "type", "conversation_id", "created_at" ] } }, "required": [ "type", "id", "attributes" ] } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "count": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": [ "total", "count", "per_page", "current_page", "total_pages" ] } }, "required": [ "pagination" ] }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "first": { "type": "string" }, "next": { "type": [ "string", "null" ] }, "last": { "type": "string" } }, "required": [ "self", "first", "next", "last" ] } }, "required": [ "data", "meta", "links" ] } } } }, "404": { "description": "Conversation not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/conversations\/{conversation_id}\/resolve": { "post": { "operationId": "api-docs.conversations.resolve", "description": "Mark a conversation as resolved or unresolved.", "summary": "Resolve Conversation", "tags": [ "Conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" }, "example": "0f46c0a1-8938-40e3-b2b5-bb56f569fcab" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "Agent ID", "examples": [ "26fa75f2-7ac1-47b4-84e1-b943491ba4da" ] }, "status": { "description": "Resolution status", "examples": [ "resolved" ], "$ref": "#\/components\/schemas\/SystemMessage" } }, "required": [ "agent_id", "status" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Conversation resolved." }, "data": { "type": "object", "properties": { "type": { "type": "string", "const": "conversations" }, "id": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "id", "attributes" ] } }, "required": [ "message", "data" ] } } } }, "404": { "description": "Conversation not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/messages": { "post": { "operationId": "messages.store", "description": "Store a new message in a conversation. In mock mode, simulates message creation with sample data.", "summary": "Create Message", "tags": [ "Messages" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/CreateMessageRequest" }, { "type": "object", "properties": { "conversation_id": { "type": "string", "description": "Conversation ID", "examples": [ "0f46c0a1-8938-40e3-b2b5-bb56f569fcab" ] }, "agent_id": { "type": [ "string", "null" ], "description": "Agent ID (optional, for internal\/note messages)", "examples": [ "26fa75f2-7ac1-47b4-84e1-b943491ba4da" ] }, "widget_id": { "type": [ "string", "null" ], "description": "Widget identifier (optional)", "examples": [ "eouqtiupanm6uvglwshy" ] } }, "required": [ "conversation_id" ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "contact_id": { "type": [ "string", "null" ] }, "agent": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ] }, "origin": { "type": "string" }, "content": { "type": "string" }, "type": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "conversation_id", "contact_id", "agent", "contact", "origin", "content", "type", "created_at" ] } }, "required": [ "type", "id", "attributes" ] } }, "required": [ "data" ] }, { "type": "object" } ] } } } }, "500": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Mock data not available. Please seed the mock conversations." ] } }, "required": [ "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "description": "Conversation not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/conversations": { "post": { "operationId": "api-docs.messages.visitor", "description": "Send a message as a visitor through a widget. Chatway picks the contact and the conversation for you,\nso no `conversation_id` is needed.\n\n### How the contact is selected\n\nIf `contact_id` matches an existing contact on this widget, it takes priority and the supplied `name`, `email`\nand `phone` are ignored. If `contact_id` is missing or not found, Chatway looks up the contact by `email`,\nthen creates a new contact if no match exists. An unknown `contact_id` does not itself cause an error.\n\nIn detail, Chatway checks these in order and uses the first match:\n\n1. **`contact_id`**: the existing contact with this ID, if it belongs to the widget in `widget_id`.\n It always takes priority over `email`.\n2. **`email`**: the most recent contact on the widget with this email. This is also used when `contact_id`\n is sent but not found on the widget.\n3. **New contact**: if nothing matches, or neither `contact_id` nor `email` is sent, a new contact is created\n from `name`, `email` and `phone`. It gets a new ID; an unknown `contact_id` is never reused as the ID.\n\nWhen an existing contact is matched, `name`, `email` and `phone` are not used to update it.\n\n### Which conversation receives the message\n\n- **Contact has a conversation:** the message is added to the contact's most recent conversation.\n If that conversation is resolved, it is reopened automatically.\n- **Contact has no conversation** (including every new contact): a new conversation is started with this message.\n\n### Reusing an initialized contact\n\nIf you created the contact with `POST \/api\/v1\/contacts\/initialize`, send the returned contact ID as `contact_id`\nwith the same widget. The message then goes to that contact instead of creating another one.\n\nNote: this endpoint uses `widget_id`, while the initialize endpoint uses `widgetId`.\nThe message text goes in the top-level `content` field.\n\n### Examples\n\n- **Existing contact:** send `widget_id`, `contact_id` and `content`.\n- **Find by email:** send `widget_id`, `email` and `content`. Add `name` and `phone` so they are saved\n if a new contact has to be created.\n- **Anonymous visitor:** send only `widget_id` and `content`. A new contact and conversation are created every time.\n\nUse `data.attributes.contact.id` from the response as `contact_id` to send more messages as the same visitor.", "summary": "Create Visitor Message", "tags": [ "Messages" ], "requestBody": { "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/CreateVisitorMessageRequest" }, { "type": "object", "properties": { "widget_id": { "type": "string", "description": "Required. Identifier of the widget the visitor writes through. It must belong to your team.", "examples": [ "eouqtiupanm6uvglwshy" ] }, "contact_id": { "type": [ "string", "null" ], "description": "Optional. ID of an existing contact on this widget. When it matches, it takes priority and `name`, `email` and `phone` are ignored. If it is not found on the widget, no error is returned: Chatway falls back to `email`, then creates a new contact with a new ID.", "examples": [ "9b0c5fe6-35ad-459d-b6ba-4288191f84f1" ] }, "name": { "type": [ "string", "null" ], "description": "Optional. Saved only when a new contact is created.", "examples": [ "Jane Doe" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Optional. Used to find an existing contact on this widget when `contact_id` is not sent or not found. Saved when a new contact is created.", "examples": [ "jane@example.com" ] }, "phone": { "type": [ "string", "null" ], "description": "Optional. Saved only when a new contact is created. 7 to 15 digits with an optional leading `+`; no spaces, dashes or brackets.", "pattern": "^\\+?[0-9]{7,15}$", "examples": [ "+15551234567" ] }, "content": { "type": "string", "description": "Required. The visitor's message text.", "examples": [ "Hi, I need help with my order." ] } }, "required": [ "widget_id", "content" ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "chat_contact_id": { "type": [ "string", "null" ] }, "agent": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ] }, "origin": { "type": "string" }, "content": { "type": "string" }, "type": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "conversation_id", "chat_contact_id", "agent", "contact", "origin", "content", "type", "created_at" ] } }, "required": [ "type", "id", "attributes" ] } }, "required": [ "data" ] }, { "type": "object" } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "description": "The widget does not exist or does not belong to your team.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/widgets": { "get": { "operationId": "api-docs.widgets.index", "description": "Retrieve a paginated list of widgets (id, name, icon). When in mock mode, returns sample widget data.", "summary": "List Widgets", "tags": [ "Widgets" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] } }, "required": [ "name", "icon" ] } }, "required": [ "type", "id", "attributes" ] } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "count": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": [ "total", "count", "per_page", "current_page", "total_pages" ] } }, "required": [ "pagination" ] }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "first": { "type": "string" }, "next": { "type": [ "string", "null" ] }, "last": { "type": "string" } }, "required": [ "self", "first", "next", "last" ] } }, "required": [ "data", "meta", "links" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } } }, "components": { "securitySchemes": { "tenant": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } }, "schemas": { "CreateMessageRequest": { "type": "object", "properties": { "conversation_id": { "type": "string" }, "content": { "type": [ "string", "null" ] }, "widget_id": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "message", "note", null ] }, "agent_id": { "type": [ "string", "null" ] }, "attachments": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "name": { "type": [ "string", "null" ] } } } } }, "required": [ "conversation_id" ], "title": "CreateMessageRequest" }, "CreateVisitorMessageRequest": { "type": "object", "properties": { "widget_id": { "type": "string" }, "contact_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ], "pattern": "^\\+?[0-9]{7,15}$" }, "content": { "type": "string" } }, "required": [ "widget_id", "content" ], "title": "CreateVisitorMessageRequest" }, "InviteAgentRequest": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ], "enum": [ "CHAT_AGENT_ADMIN", "CHAT_AGENT_MEMBER", null ] } }, "required": [ "email" ] }, "minItems": 1 } }, "required": [ "agents" ], "title": "InviteAgentRequest" }, "StorePublicChatContactRequest": { "type": "object", "properties": { "widgetId": { "type": "string" }, "browser_type": { "type": [ "string", "null" ] }, "operating_system": { "type": [ "string", "null" ] }, "ip": { "type": [ "string", "null" ] }, "is_simulator": { "type": [ "boolean", "null" ] }, "language": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "country_dialing_code": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email" }, "preferred_chat_language": { "type": [ "string", "null" ], "enum": [ "auto-detect", "en", "pt", "es", "de", "fr", "ja", "ru", "da", "fi", "it", "tr", "zh", "ab", "ace", "ach", "af", "sq", "alz", "am", "ar", "hy", "as", "awa", "ay", "az", "ban", "bm", "ba", "eu", "btx", "bts", "bbc", "be", "bem", "bn", "bew", "bho", "bik", "bs", "br", "bg", "bua", "yue", "ca", "ceb", "ny", "zh-TW", "cv", "co", "crh", "hr", "cs", "din", "dv", "doi", "dov", "nl", "dz", "eo", "et", "ee", "fj", "fil", "fr-FR", "fr-CA", "fy", "ff", "gaa", "gl", "ka", "el", "gn", "gu", "gv", "ht", "cnh", "ha", "haw", "he", "iw", "hi", "hmn", "hu", "hrx", "is", "ig", "ilo", "id", "ga", "jv", "jw", "kn", "pam", "kk", "km", "cgg", "rw", "ktu", "gom", "ko", "kri", "ku", "ckb", "ky", "lo", "ltg", "la", "lv", "lij", "li", "ln", "lt", "lmo", "luo", "lb", "lg", "mk", "mai", "mak", "mg", "ms", "ms-Arab", "ml", "mt", "mi", "mr", "mni-Mtei", "min", "lus", "mn", "my", "nr", "new", "ne", "no", "nus", "oc", "or", "om", "pag", "pap", "ps", "fa", "pl", "pt-PT", "pt-BR", "pa", "qu", "rom", "ro", "rn", "sm", "sg", "sa", "gd", "nso", "sr", "st", "crs", "shn", "sn", "scn", "szl", "sd", "si", "sk", "sl", "so", "su", "sw", "ss", "sv", "tl", "tg", "ta", "tt", "te", "tet", "th", "ti", "ts", "tn", "tk", "ak", "uk", "ur", "ug", "uz", "vi", "cy", "xh", "yi", "yo", "yua", "zu", "zh-CN", "ak", "gom", null ] }, "phone": { "type": [ "string", "null" ], "maxLength": 20 }, "marketplace_channel": { "type": [ "string", "null" ], "maxLength": 20 }, "marketplace_origin": { "type": [ "string", "null" ], "maxLength": 255 }, "is_form_auto_submitted": { "type": [ "boolean", "null" ] }, "message": { "type": "object", "properties": { "urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "content": { "type": [ "string", "null" ] } } }, "page_visited": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "page": { "type": [ "string", "null" ] }, "date": { "type": "string", "format": "date-time" } } } } }, "required": [ "widgetId" ], "title": "StorePublicChatContactRequest" }, "SystemMessage": { "type": "string", "enum": [ "resolved", "unresolved", "contact_blocked", "contact_unblocked", "ended", "reopened" ], "title": "SystemMessage" }, "UpdateChatContactRequest": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 255 } }, "title": "UpdateChatContactRequest" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } }, "webhooks": { "guides.mcp_overview": { "post": { "operationId": "guides.mcp_overview", "description": "# MCP overview\n\nThe Chatway MCP server lets an AI assistant \u2014 Claude, ChatGPT, Cursor, Codex, Grok, Muse, or\nanything else that speaks the [Model Context Protocol](https:\/\/modelcontextprotocol.io) \u2014 work\ninside your Chatway workspace using plain language.\n\n## Connect Chatway to an AI assistant\n\n1. Copy the MCP server URL:\n\n```\nhttps:\/\/mcp.chatway.app\/mcp\n```\n\n2. Add it as a remote MCP server in Claude, ChatGPT, Cursor, Codex, or another MCP client.\n3. Sign in to Chatway and choose the widgets, channels, and permissions the assistant can access.\n\nThat's it \u2014 no API key to paste. Client-specific steps are on\n[Connect clients](\/mcp\/guides.mcp_connect_clients).\n\n**Test your connection** by asking your assistant:\n\n> List my 5 most recent Chatway conversations.\n\n## MCP, webhooks, or the REST API?\n\nChatway offers three ways to connect an external system, and they solve different problems.\n\n| | MCP | Webhooks | REST API |\n| --- | --- | --- | --- |\n| Direction | Your assistant \u2192 Chatway | Chatway \u2192 your server | Your code \u2192 Chatway |\n| What starts it | You ask your assistant | A visitor does something | Your code decides |\n| What decides the outcome | The model | Your code | Your code |\n| Do you write code? | No | Yes | Yes |\n| Auth | OAuth | Signed secret | `X-API-KEY` |\n| Set up in | Your MCP client | **Settings \u2192 Developer Tools \u2192 Webhooks** | **Settings \u2192 Developer Tools \u2192 API Keys** |\n\n**Choose MCP** when a person wants to work through an assistant on demand \u2014 triaging a queue,\nsummarising a thread, drafting a reply. There is nothing to build, and the model decides which\ntools to call, which is exactly why it suits open-ended work and not fixed rules.\n\n**Choose webhooks** when something in Chatway should trigger your system in real time, most\noften so an agent can answer visitors automatically the moment they write in.\n\n**Choose the REST API** when you want behaviour that is exact and repeatable, with no model in\nthe loop: syncing conversations into your warehouse, provisioning contacts from your CRM,\nback-office scripts, scheduled reports, or your own dashboard. If a wrong call would be\nexpensive, or the same input must always produce the same result, use the REST API rather than\nasking an assistant to do it.\n\nThey combine well. A common setup uses webhooks to notify an agent, the REST API for that agent\nto reply deterministically, and MCP so the support team can still ask questions in natural\nlanguage over the same inbox. See the **API Reference** in the sidebar for endpoints, and\n**Quickstart** for the receive-a-message-and-reply loop.\n\n## What MCP gives you\n\nOnce connected, your assistant can work in your inbox conversationally:\n\n> \"How many conversations are still unresolved on the marketing widget?\"\n>\n> \"Summarise the last conversation with john@example.com, then reply asking for their order number.\"\n>\n> \"Tag every conversation from today that mentions refunds.\"\n\nIt does this by calling tools you explicitly authorized. It never gets your password, and you\nnever paste an API key into it.\n\nThe endpoint is a streamable HTTP MCP server and accepts `POST` requests. It is separate from the\nREST API: the REST API authenticates with an `X-API-KEY` header, MCP with OAuth.\n\n## Authentication\n\nMCP clients use OAuth 2.1 with PKCE and request the `mcp:use` scope. Chatway supports dynamic\nclient registration, so your client handles the whole exchange and you never create a client ID\nor secret.\n\n1. Your client discovers Chatway's authorization server from the MCP endpoint.\n2. A browser opens and you sign in to Chatway.\n3. You name the connection, so you can recognise it later.\n4. You choose which **widgets and channels** the assistant may access.\n5. You choose which **permissions** to grant, and which **agent** replies are sent as.\n6. Chatway issues an access token scoped to exactly those choices and returns you to your client.\n\nEvery connection belongs to your **team workspace**, not to an individual teammate. **Owners and\nadmins** manage that connection under **AI \u2192 External AI**. Re-authorizing the same assistant client\n(for example Claude or Cursor) updates the team connection instead of creating a second one.\n\n## What assistants can do\n\nTwenty-one tools are available. Each requires a matching permission, so an assistant only sees the\ntools you actually granted.\n\n| Group | Tools |\n| --- | --- |\n| Read conversations | `list-conversations`, `get-conversation`, `list-conversation-messages`, `search-conversations` |\n| Read people | `get-visitor`, `search-contacts` |\n| Read settings | `search-knowledge-base`, `list-tags`, `list-custom-fields`, `list-agents` |\n| Reply and triage | `send-message`, `resolve-conversation`, `unresolve-conversation`, `assign-conversation` |\n| Annotate | `add-note`, `add-tag`, `remove-tag` |\n| Custom data | `add-custom-data`, `update-custom-data`, `remove-custom-data` |\n| Escalate | `handoff-to-human` |\n\n`handoff-to-human` uses the same handover behaviour as Chatway's built-in AI agent, so your team\ngets the notifications and inbox state they already expect.\n\nFor each tool's parameters, return shape, and limits, see the\n[Tool reference](\/mcp\/guides.mcp_tool_reference).\n\n## Scope of access\n\nA connection can only reach the widgets and channels you selected. It sees nothing from your\nother widgets, and it can never reach data belonging to another team. Both are enforced on every\nrequest, independently of which permissions you granted.\n\nPermissions also respect your Chatway role. Only **owners and admins** can run the MCP OAuth flow\nto connect or reconnect an assistant and open **AI \u2192 External AI** in Settings. **Members** do not\nhave access to that menu. Write permissions on a connection can only be granted by an owner or\nadmin.\n\n## Safety on bulk and destructive actions\n\nSome actions ask for confirmation before Chatway will run them. Instead of acting straight away,\nthe assistant has to put the question to you first, along with how much it is about to affect:\n\n> This action will resolve 100 conversations. Are you sure?\n\nConfirm and it proceeds. Your approval lasts 5 minutes and is tied to that exact action, so an\nassistant cannot reuse it for anything else.\n\nResolving, unresolving, or assigning conversations requires confirmation, including when acting\non a single conversation. Removing a tag or removing custom data also requires confirmation.\n\n## Rate limits\n\nMCP requests are limited to **120 requests per minute per connection**. Each connection has its\nown budget, so a busy assistant cannot slow down your other connections. Over the limit, the\nserver returns `429` and the assistant should retry after a short pause.\n\n## Replying in real time with webhooks\n\nMCP is on-demand: the assistant acts when you ask it to. If you want your AI agent to answer\nvisitors **automatically as soon as they send a message**, use Chatway webhooks together with\nthe REST API.\n\n```\nVisitor \u2192 Chatway \u2192 webhook \u2192 your AI agent \u2192 Chatway API \u2192 visitor\n```\n\nChatway POSTs a signed event to your endpoint, your agent decides what to say, and it replies\nthrough the REST API. Alongside the reply your agent can record optional confidence and model\ndetails, which is useful for tracking how well it is performing before you let it handle\neverything.\n\nYou can also connect the same agent through MCP for on-demand access to your Chatway workspace \u2014\ntriaging the queue, summarizing threads, or taking actions in natural language. MCP is optional\nfor the real-time loop above; webhooks and the REST API are enough on their own.\n\nThirteen events are available, including the ones most agents need:\n\n| Event | Fires when |\n| --- | --- |\n| `conversation.created` | A new chat has started |\n| `message.received` | A visitor sent a new message |\n| `conversation.resolved` | A conversation was resolved |\n| `agent.assigned` | An agent was assigned to a conversation |\n| `contact.form.submitted` | A visitor submitted a contact or offline form |\n\nYour agent can then use the REST API to reply, resolve, unresolve, star, assign, note, tag,\nupdate custom data, or trigger a human handoff \u2014 the same actions available over MCP.\n\nSet this up under **Settings \u2192 Developer Tools \u2192 Webhooks**, and see **Webhook docs \u2192 Overview**\nin the sidebar for the full event list, payload shapes, signature verification, and retries.\n**Quickstart** walks through the receive-a-message-and-reply loop end to end.\n\n## Next steps\n\n- [Connect clients](\/mcp\/guides.mcp_connect_clients) \u2014 set up Claude, ChatGPT, Codex, Cursor, Muse, and the rest.\n- [Tool reference](\/mcp\/guides.mcp_tool_reference) \u2014 every tool, its parameters, and what it returns.\n- [Permissions & access](\/mcp\/guides.mcp_permissions_and_access) \u2014 what each permission unlocks.\n- [Manage connections](\/mcp\/guides.mcp_manage_connections) \u2014 review, edit, and revoke access.\n", "summary": "Overview", "security": [], "x-codeSamples": [], "x-chatway-docs-section": "mcp" } }, "guides.mcp_connect_clients": { "post": { "operationId": "guides.mcp_connect_clients", "description": "# Connect clients\n\nAny MCP client that supports remote servers over HTTP can connect to Chatway. Point it at the\nChatway MCP endpoint and complete the sign-in prompt \u2014 there is no client ID or secret to create,\nbecause Chatway registers your client automatically.\n\n**Server URL**\n\n```\nhttps:\/\/mcp.chatway.app\/mcp\n```\n\nChatway recognises Claude, ChatGPT, Cursor, Codex, Gemini, Grok, VS Code, OpenCode, Manus, Muse,\nDevin, Cline, and Goose, and labels the connection with that name so you can tell your\nconnections apart. Any other client is recorded as a custom integration.\n\n## Before you start\n\nDuring sign-in you choose four things. It helps to know them in advance:\n\n| Choice | Notes |\n| --- | --- |\n| Connection name | How this connection appears in Chatway. Use something like \"Claude \u2013 support triage\". |\n| Widgets & channels | Which inboxes the assistant may touch. All are selected by default. |\n| Permissions | What the assistant may read and do. Write permissions need owner or admin. |\n| Reply as | The agent that replies and other write actions are attributed to. Defaults to you. |\n\nYou can change all four later without reconnecting. See\n[Manage connections](\/mcp\/guides.mcp_manage_connections).\n\n## Where to add it\n\nMost clients now have a UI for this, so you rarely need to edit a config file.\n\n| Client | Add it here |\n| --- | --- |\n| Claude | **Customize \u2192 Connectors \u2192 Add custom connector** |\n| Claude Code | `claude mcp add --transport http` |\n| ChatGPT | **Browse Plugins \u2192 \"+\"** (Developer mode on; web only) |\n| Codex | **Settings \u2192 MCP servers \u2192 Add server** |\n| Gemini | `gemini extensions install https:\/\/github.com\/Chatway-app\/chatway-mcp-server` \u00b7 `\/mcp auth chatway` |\n| Cursor | **Customize \u2192 MCPs** |\n| GitHub Copilot (VS Code) | Command Palette \u2192 **MCP: Add Server** |\n| Grok | **grok.com\/connectors \u2192 New Connector \u2192 Custom** |\n| Devin | **Settings \u2192 Cascade \u2192 Manage MCPs \u2192 Add Server** |\n| Cline | IDE extension: **MCP Servers \u2192 Remote Servers** \u00b7 CLI: `cline mcp install` |\n| Goose | **Extensions \u2192 Add custom extension** |\n| Manus | **Settings \u2192 MCP \/ Connectors** |\n| Muse | **Settings \u2192 MCP Servers** |\n| OpenCode | `opencode mcp add` |\n\n## Claude\n\nWorks with claude.ai, Claude Desktop, Cowork, and the mobile apps.\n\n**Free, Pro, and Max plans**\n\n1. Go to **Customize \u2192 Connectors**.\n2. Click **+**, then **Add custom connector**.\n3. Enter a name and paste the Chatway server URL.\n4. Click **Add**, then **Connect** and complete the Chatway sign-in flow.\n\nFree plans are limited to one custom connector.\n\n**Team and Enterprise plans**\n\nOnly an Owner can add the connector, and each member then connects individually so Claude only\nreaches inboxes that person can already access.\n\n1. An Owner goes to **Organization settings \u2192 Connectors**.\n2. Click **Add**, hover **Custom**, and choose **Web**.\n3. Paste the Chatway server URL and click **Add**.\n4. Each member then opens **Settings \u2192 Connectors**, finds the connector labelled **Custom**, and\n clicks **Connect**.\n\nLeave the OAuth Client ID and Secret fields in **Advanced settings** empty \u2014 Chatway registers\nClaude automatically.\n\n> Claude reaches your MCP server from Anthropic's cloud, not from your computer. This is true\n> even in Claude Desktop, so the server has to be reachable over the public internet.\n\n## Claude Code\n\nOne command in your terminal:\n\n```bash\nclaude mcp add --transport http --scope user chatway \"https:\/\/mcp.chatway.app\/mcp\"\n```\n\n`--scope user` makes Chatway available in every project. Leave it off and the server is only\nadded to the project you ran the command in, which is the most common reason it seems to vanish.\n\n`claude mcp list` then shows `! Needs authentication`. Start a session, run `\/mcp`, select\n**chatway**, and choose **Authenticate**. Your browser opens the Chatway sign-in. After you\napprove, the status should be `\u2714 Connected`.\n\nSome CLI versions also accept `claude mcp login chatway` for the same browser flow.\n\n## ChatGPT\n\nCustom MCP apps are set up on **chatgpt.com (web only)** \u2014 not in the mobile app. OpenAI documents\nthem under **Apps**, with Developer mode required before you can create or use a custom MCP app.\n\n**Plan differences (per OpenAI)**\n\n| Plan | Custom MCP apps |\n| --- | --- |\n| Free | Not available |\n| Plus \/ Pro | Developer mode available. Pro can connect custom MCP apps with **read\/fetch** permissions. |\n| Business, Enterprise, Edu | Full MCP including **write\/modify** tools (admin-controlled). Workspace admins enable Developer mode, create and test apps, then publish them for the workspace. |\n\nExact labels move occasionally; if a path below does not match your account, look under\n**Settings \u2192 Apps** or **Workspace settings \u2192 Apps**.\n\n**1. Turn on Developer mode**\n\n1. Open **Settings \u2192 Apps** (or **Workspace settings \u2192 Apps** on Business \/ Enterprise \/ Edu).\n2. Open **Apps** settings and turn **Developer mode** on.\n\nEach admin or owner must enable Developer mode for themselves \u2014 the toggle does not apply to the\nwhole workspace at once.\n\n**2. Create the app**\n\n1. Go to the **Browse Plugins** page and click **\"+\"** to add a new plugin.\n2. Fill in:\n\n| Field | Value |\n| --- | --- |\n| Name | `Chatway` |\n| Description | Access your Chatway inbox and take actions |\n| MCP Server URL | `https:\/\/mcp.chatway.app\/mcp` |\n| Authentication | **OAuth** |\n\n3. Leave Client ID and Client Secret empty \u2014 Chatway registers ChatGPT automatically.\n4. Complete the Chatway sign-in flow.\n\nCreated apps often appear under **Drafts** until you publish them for a workspace.\n\n**3. Use it in a chat**\n\n1. Start a new conversation on the web.\n2. Open the **+** menu and choose **Developer mode**.\n3. Enable the Chatway app.\n\nAsk something read-only first, such as \"List my 5 most recent Chatway conversations.\" ChatGPT\nconfirms write actions separately in the conversation, on top of Chatway's own confirmation for\nbulk and destructive tools.\n\n**Business, Enterprise, and Edu.** A workspace admin must allow custom apps, create and test the\napp, then publish it from **Workspace settings \u2192 Apps**. Enterprise\/Edu admins can further limit\nwho gets Developer mode and which published apps each person can use. After you change permissions\nin Chatway, refresh the app so ChatGPT picks up the new tool list.\n\n## Codex\n\nCodex shares one MCP configuration across the ChatGPT desktop app, the CLI, and the IDE\nextension. Add it once and it is available in all three.\n\n**Desktop app (recommended)**\n\n1. Open **Settings \u2192 MCP servers**.\n2. Select **Add server**.\n3. Enter `chatway` as the name, choose **Streamable HTTP**, and paste the server URL.\n4. Save, then select **Restart**.\n5. Click **Authenticate** on the `chatway` row and complete sign-in.\n\nLeave bearer token and header fields blank \u2014 Chatway uses OAuth. Type `\/mcp` in the composer to\nsee connected servers.\n\n**IDE extension**\n\nOpen the gear menu \u2192 **MCP servers \u2192 Add server**, enter the same details, then **Restart\nextension**. Click **Authenticate** if the row asks for it.\n\n**CLI**\n\n```bash\ncodex mcp add chatway --url \"https:\/\/mcp.chatway.app\/mcp\"\ncodex mcp login chatway\n```\n\n**Config file**\n\nFor project-only access, edit `.codex\/config.toml` in a trusted project (or `~\/.codex\/config.toml`\nfor every project):\n\n```toml\n[mcp_servers.chatway]\nurl = \"https:\/\/mcp.chatway.app\/mcp\"\n```\n\nThen run `codex mcp login chatway`. Do not set `bearer_token_env_var` or `http_headers`.\n\n## Gemini\n\nThe [Gemini CLI](https:\/\/github.com\/google-gemini\/gemini-cli) connects to remote MCP servers over\n**streamable HTTP** and completes OAuth in your local browser. Dynamic client registration uses the\ndisplay name **Gemini CLI MCP Client**; Chatway recognises that client as **Gemini** so reconnects\nupdate the same connection instead of creating duplicates.\n\n### Recommended: install the Chatway extension\n\n1. Install the official Chatway extension:\n\n ```bash\n gemini extensions install https:\/\/github.com\/Chatway-app\/chatway-mcp-server\n ```\n\n2. Start `gemini` and run `\/mcp auth chatway` to sign in.\n3. Run `\/mcp list` to confirm the `chatway` server is connected.\n\nThe extension also loads Chatway-specific guidance into Gemini (for example, confirming before\nsending customer replies). Update it with `gemini extensions update chatway` and remove it with\n`gemini extensions uninstall chatway`.\n\n### Alternative: add the server manually\n\n1. Edit `~\/.gemini\/settings.json` (create the file if needed).\n2. Add a `chatway` entry under `mcpServers` with `httpUrl` set to the Chatway server URL.\n3. Start the CLI, connect to the server, or run `\/mcp auth chatway` when prompted.\n\n```json\n{\n \"mcpServers\": {\n \"chatway\": {\n \"httpUrl\": \"https:\/\/mcp.chatway.app\/mcp\"\n }\n }\n}\n```\n\nUse one method, not both, so you don't end up with two `chatway` servers.\n\nOAuth requirements from Google:\n\n- A local browser must open for sign-in.\n- Redirects use loopback (`http:\/\/127.0.0.1` or `http:\/\/localhost`, often with `\/oauth\/callback`).\n- Optional `redirectUri` in server config pins the port if your environment needs it.\n\nTokens are stored in `~\/.gemini\/mcp-oauth-tokens.json`. Re-run `\/mcp auth chatway` if access\nexpires. See the [Gemini CLI MCP server guide](https:\/\/github.com\/google-gemini\/gemini-cli\/blob\/main\/docs\/tools\/mcp-server.md)\nfor transport details and advanced OAuth options.\n\n## Cursor\n\n**UI**\n\n1. Open **Customize** in the sidebar and click **MCPs**.\n2. Click **Add Custom MCP** (or **New MCP Server**).\n3. Add the Chatway entry below, save, and complete the browser sign-in.\n\nYou can also open **Cursor Settings \u2192 Tools & MCP** and click **+ Add Custom MCP** \u2014 it writes\nthe same `mcp.json` file.\n\n**Config file**\n\n`.cursor\/mcp.json` for one project, `~\/.cursor\/mcp.json` for all of them:\n\n```json\n{\n \"mcpServers\": {\n \"chatway\": {\n \"url\": \"https:\/\/mcp.chatway.app\/mcp\"\n }\n }\n}\n```\n\nCursor infers the transport from the presence of `url`, so no `type` field is needed. Leave out\n`headers` and `auth` as well; Chatway uses dynamic registration, so the OAuth flow starts on its\nown.\n\n## GitHub Copilot (VS Code)\n\nUse Chatway from GitHub Copilot Chat in VS Code. Requires Copilot Chat in **Agent** mode.\n\n1. Open the Command Palette (`Cmd\/Ctrl + Shift + P`) and run **MCP: Add Server**.\n2. Choose **HTTP** (not stdio), then **Workspace** or **Global**.\n3. Paste the Chatway server URL and a name of `chatway`.\n4. Trust the server when VS Code asks, then complete Chatway sign-in.\n\nOr edit `mcp.json` yourself \u2014 `.vscode\/mcp.json` for the workspace, or **MCP: Open User\nConfiguration** for the global file:\n\n```json\n{\n \"servers\": {\n \"chatway\": {\n \"type\": \"http\",\n \"url\": \"https:\/\/mcp.chatway.app\/mcp\"\n }\n }\n}\n```\n\nTwo VS Code specifics matter here. The root key is **`servers`**, not `mcpServers` \u2014 a block\ncopied from Cursor is valid JSON and gets silently ignored. And `\"type\": \"http\"` is **required**;\nwithout it VS Code treats the entry as a local process and fails. Run **MCP: List Servers** to\nconfirm Chatway loaded and see its tool count.\n\nOne-click install from the [GitHub MCP Registry](https:\/\/github.com\/mcp) (searching\n`@mcp Chatway` in the VS Code Extensions view) will be available once Chatway is accepted into\nGitHub's curated registry. Until then, add the server manually as described above.\n\n## Grok\n\nCustom connectors are available on Grok's paid tiers.\n\n1. Go to [grok.com\/connectors](https:\/\/grok.com\/connectors).\n2. Click **New Connector**, then select **Custom**.\n3. Enter `Chatway` as the name and paste the server URL.\n4. Complete the Chatway sign-in flow.\n\nGrok then discovers Chatway's tools and offers them in conversations alongside its built-in\nconnectors.\n\nOn **Business and Enterprise** plans a team admin has to provision it first: sign in to\n[console.x.ai](https:\/\/console.x.ai), select your team, go to **Grok Business \u2192 Connectors**,\nclick **+ Add Connector**, choose **Other**, and enter the server URL.\n\n## Devin\n\n1. Open **Devin Settings \u2192 Cascade \u2192 Manage MCPs**.\n2. Click **+ Add Server**, then **View raw config** to edit the JSON.\n3. Add the Chatway entry, save, and click **Refresh**.\n\n```json\n{\n \"mcpServers\": {\n \"chatway\": {\n \"serverUrl\": \"https:\/\/mcp.chatway.app\/mcp\"\n }\n }\n}\n```\n\nDevin uses **`serverUrl`**, not `url`, for remote servers. A config copied from Cursor parses\nfine but leaves Devin with no endpoint, so the server appears to load and then shows zero\ntools. The file lives at `~\/.config\/devin\/mcp_config.json`, and Devin only supports global configuration. Click **Refresh** after every\nedit.\n\n## Cline\n\nCline runs as a standalone **CLI** and as an **IDE extension** (VS Code, JetBrains, and other\nsupported editors). The **Remote Servers** UI in the Cline panel is available **only after you\ninstall the extension in an IDE** \u2014 it is not part of the terminal-only CLI. If you use Cline from\nthe command line, add Chatway with `cline mcp install` or `cline mcp` instead.\n\nSee the [Cline MCP overview](https:\/\/docs.cline.bot\/mcp\/mcp-overview) for the latest client\ndetails.\n\n### IDE extension (Remote Servers UI)\n\n1. Install the Cline extension in your editor and open the Cline panel.\n2. Click the **MCP Servers** icon.\n3. Open the **Remote Servers** tab.\n4. Enter `chatway` as the server name and paste the server URL.\n5. Choose **Streamable HTTP** as the transport type.\n6. Click **Add Server** and complete Chatway sign-in when prompted.\n\nYou can also open **Configure \u2192 Configure MCP Servers** to edit the extension\u2019s MCP JSON directly.\n\n### CLI (`cline mcp install`)\n\nFrom a terminal (requires a TTY), pre-fill the server and open Cline\u2019s add-server wizard. It still\nprompts for auth (including OAuth) before saving to `~\/.cline\/data\/settings\/cline_mcp_settings.json`:\n\n```bash\ncline mcp install chatway --transport http https:\/\/mcp.chatway.app\/mcp\n```\n\n`cline mcp add` is an alias for `cline mcp install`. For the full menu (list, edit, enable, delete\nservers), run:\n\n```bash\ncline mcp\n```\n\nChoose **Add server**, pick **Remote (HTTP)**, name it `chatway`, paste the Chatway URL, and\ncomplete OAuth when asked. Non-interactive listing: `cline config mcp`.\n\n### Manual JSON\n\nIf you edit JSON instead of using the Remote Servers form, the `type` field is not optional.\nCLI config lives at `~\/.cline\/data\/settings\/cline_mcp_settings.json` (override with the\n`CLINE_MCP_SETTINGS_PATH` environment variable); the IDE extension uses its own MCP settings file opened\nfrom **Configure MCP Servers**.\n\n```json\n{\n \"mcpServers\": {\n \"chatway\": {\n \"type\": \"streamableHttp\",\n \"url\": \"https:\/\/mcp.chatway.app\/mcp\",\n \"disabled\": false\n }\n }\n}\n```\n\nOmitting `type` makes Cline fall back to legacy SSE, which fails against Chatway with a `400`\nbecause it sends a `GET` where Chatway expects a `POST`.\n\n## Goose\n\n**Desktop**\n\n1. Open **Extensions \u2192 Add custom extension**.\n2. Choose **Remote (Streamable HTTP)**.\n3. Enter `chatway` as the name and the Chatway server URL as the endpoint.\n4. Complete sign-in when prompted.\n\n**CLI**\n\n```bash\ngoose configure\n```\n\nChoose **Add Extension \u2192 Remote Extension (Streamable HTTP)**, then enter `chatway` and the\nChatway URL.\n\nTo edit `~\/.config\/goose\/config.yaml` directly:\n\n```yaml\nextensions:\n chatway:\n enabled: true\n type: streamable_http\n name: chatway\n uri: https:\/\/mcp.chatway.app\/mcp\n timeout: 300\n```\n\nGoose differs from every other client on three counts: the top-level key is `extensions`, the\nendpoint field is `uri`, and the transport is `streamable_http` with an underscore. Restart Goose\nafter editing the file.\n\n## OpenCode\n\nThe interactive command is the current way:\n\n```bash\nopencode mcp add\n```\n\nChoose a remote server, name it `chatway`, and paste the Chatway URL. Then authenticate:\n\n```bash\nopencode mcp auth chatway\nopencode mcp list\n```\n\nOr write `opencode.json` yourself (project root, or `~\/.config\/opencode\/opencode.json` globally):\n\n```json\n{\n \"$schema\": \"https:\/\/opencode.ai\/config.json\",\n \"mcp\": {\n \"chatway\": {\n \"type\": \"remote\",\n \"url\": \"https:\/\/mcp.chatway.app\/mcp\",\n \"enabled\": true\n }\n }\n}\n```\n\nLeave `oauth` unset so OpenCode uses dynamic registration. Do not set `oauth: false` \u2014 that is\nonly for API-key servers.\n\n## Manus\n\n1. Open [Manus](https:\/\/manus.im\/) and go to **Settings \u2192 MCP \/ Connectors**.\n2. Choose **Add custom MCP server**.\n3. Paste the Chatway server URL.\n4. Sign in to Chatway and select the widgets and channels to connect.\n\n## Muse\n\nWorks with [Muse Code](https:\/\/meta-models.github.io\/muse-code-sdk\/next\/guides\/extend\/mcp-servers\/)\nand other MCP-compatible Muse clients.\n\n1. Open your Muse settings and go to **MCP Servers**.\n2. Add a new **remote MCP server** (streamable HTTP).\n3. Enter **Chatway** as the server name.\n4. Paste the Chatway MCP connection URL:\n\n```\nhttps:\/\/mcp.chatway.app\/mcp\n```\n\n5. Save the configuration and start a new Muse session.\n6. When prompted, sign in to Chatway and authorize the widgets, channels, and permissions you\n want Muse to access.\n\n**CLI alternative.** If the session reports that the server requires OAuth, run\n`muse mcp login chatway` (use the server name you chose in settings). Muse registers the OAuth\nclient dynamically \u2014 leave Client ID and Client Secret empty in any advanced fields.\n\nOfficial reference:\n[MCP servers in Muse Code](https:\/\/meta-models.github.io\/muse-code-sdk\/next\/guides\/extend\/mcp-servers\/).\n\n**OAuth allowlist.** Muse Code registers via dynamic client registration. Loopback callbacks\n(`http:\/\/127.0.0.1` \/ `http:\/\/localhost`) and the `muse:\/\/` redirect scheme are on Chatway's MCP\nOAuth allowlist \u2014 no manual client ID or secret.\n\n## Any other client\n\nMost clients accept the standard remote server format:\n\n```json\n{\n \"mcpServers\": {\n \"chatway\": {\n \"url\": \"https:\/\/mcp.chatway.app\/mcp\"\n }\n }\n}\n```\n\nLook for a \"remote MCP server\" or \"streamable HTTP\" option, restart or reload the client if it\nasks, and complete Chatway's sign-in on first use. Chatway speaks streamable HTTP and supports\nOAuth 2.1 with PKCE and dynamic client registration, so no manual credentials are needed.\n\n## Completing authorization\n\nThe first request from a new client starts the OAuth flow in your browser:\n\n1. Sign in to Chatway, or continue with your existing session.\n2. Name the connection.\n3. Select the widgets and channels the assistant may access.\n4. Review the permissions, pick the agent replies are sent as, and authorize.\n5. You are returned to your client, which stores the token and reconnects silently from then on.\n\nYou must grant at least one read permission and select at least one widget or channel, otherwise\nthe connection would have nothing to work with.\n\n## Verify the connection\n\nAsk the assistant something read-only:\n\n> List my 5 most recent Chatway conversations.\n\nIf it answers with real conversations, you are connected. **Owners and admins** also see the\nconnection in Chatway under **AI \u2192 External AI**.\n\n## Troubleshooting\n\nMost failures are one of two things: the client never finished the OAuth flow, or the config uses\na key name that client does not read.\n\n| Symptom | Cause and fix |\n| --- | --- |\n| No Chatway tools appear at all | The OAuth flow did not finish, or the connection was disconnected. Inbox tools are only published once a live connection exists \u2014 reconnect the client. |\n| Server loads but shows zero tools | Usually a wrong endpoint key. Devin needs `serverUrl`, Goose needs `uri`, everyone else uses `url`. |\n| VS Code ignores the entry entirely | The root key must be `servers`, not `mcpServers`, and `\"type\": \"http\"` is required. |\n| Cline returns `400` | Set `\"type\": \"streamableHttp\"`. Without it Cline uses legacy SSE. |\n| ChatGPT shows only `search` \/ `fetch` | Developer mode is off, or your plan only allows read\/fetch MCP. Turn Developer mode on under **Settings \u2192 Apps**, and use Business \/ Enterprise \/ Edu for full write tools. |\n| ChatGPT has no Create button | You are on the free plan, not on the web app, or a workspace admin has not allowed custom apps. |\n| Claude Code can't find the server | It was added at project scope. Re-add it with `--scope user`. |\n| `401` with a `WWW-Authenticate` header | The token is missing, expired, or revoked. Reconnect the client. |\n| `403 insufficient_scope` | The token lacks the `mcp:use` scope. Remove the server from your client and add it again. |\n| `403` on one specific tool | That permission was not granted, or your role does not allow it. See [Permissions & access](\/mcp\/guides.mcp_permissions_and_access). |\n| \"Conversation not found for the authorized sources\" | The conversation belongs to a widget or channel this connection cannot access. Add it under **Manage access**. |\n| `405` | The endpoint only accepts `POST`. Let your MCP client handle the transport rather than opening the URL in a browser. |\n| `429` | You hit the 120 requests per minute limit for this connection. Retry after a short delay. |\n| Assistant asks to confirm an action | Expected for bulk and destructive actions. See [Tool reference](\/mcp\/guides.mcp_tool_reference). |\n| OpenCode never starts OAuth | Do not set `oauth: false`. Leave `oauth` unset and run `opencode mcp auth chatway`. |\n", "summary": "Connect clients", "security": [], "x-codeSamples": [], "x-chatway-docs-section": "mcp" } }, "guides.mcp_tool_reference": { "post": { "operationId": "guides.mcp_tool_reference", "description": "# Tool reference\n\nChatway exposes 21 MCP tools. This page documents every one: its parameters, what it returns,\nthe permission it needs, and when it asks for confirmation.\n\nYou do not normally call these yourself \u2014 your assistant does. Use this page when you are\nbuilding an integration, debugging a failed call, or writing instructions that steer an\nassistant toward the right tool.\n\n## Tool index\n\n| Tool | Permission | Confirmation |\n| --- | --- | --- |\n| [`list-conversations`](#list-conversations) | `read_conversations` | \u2014 |\n| [`get-conversation`](#get-conversation) | `read_conversations` | \u2014 |\n| [`list-conversation-messages`](#list-conversation-messages) | `read_conversation_messages` | \u2014 |\n| [`search-conversations`](#search-conversations) | `read_conversations` | \u2014 |\n| [`get-visitor`](#get-visitor) | `read_visitor_details` | \u2014 |\n| [`search-contacts`](#search-contacts) | `search_contacts` | \u2014 |\n| [`search-knowledge-base`](#search-knowledge-base) | `search_knowledge_base` | \u2014 |\n| [`list-tags`](#list-tags) | `view_tags` | \u2014 |\n| [`list-custom-fields`](#list-custom-fields) | `view_custom_fields` | \u2014 |\n| [`list-agents`](#list-agents) | `assign_conversations` | \u2014 |\n| [`send-message`](#send-message) | `send_replies` | \u2014 |\n| [`resolve-conversation`](#resolve-conversation) | `resolve_conversations` | Bulk |\n| [`unresolve-conversation`](#unresolve-conversation) | `unresolve_conversations` | Bulk |\n| [`assign-conversation`](#assign-conversation) | `assign_conversations` | Bulk |\n| [`add-note`](#add-note) | `add_notes` | \u2014 |\n| [`add-tag`](#add-tag) | `add_tags` | \u2014 |\n| [`remove-tag`](#remove-tag) | `remove_tags` | Always |\n| [`add-custom-data`](#add-custom-data) | `add_custom_data` | \u2014 |\n| [`update-custom-data`](#update-custom-data) | `update_custom_data` | \u2014 |\n| [`remove-custom-data`](#remove-custom-data) | `remove_custom_data` | Always |\n| [`handoff-to-human`](#handoff-to-human) | `request_human_handoff` | \u2014 |\n\n## Conventions\n\nThese rules apply to every tool.\n\n| | |\n| --- | --- |\n| Identifiers | Every `*_id` is a UUID. |\n| Scope | Results are always limited to the widgets and channels the connection was granted. A conversation outside that set behaves as if it does not exist. |\n| Permissions | A tool is only published to the assistant if its permission was granted. Calling one without permission returns an error. |\n| Rate limit | 120 requests per minute per connection, then `429`. |\n| Visibility | Inbox tools only appear once a live connection exists. A disconnected connection publishes none. The MCP server may still expose internal diagnostic tools to assistants only \u2014 these are not configurable in Chatway. |\n\nRead tools are marked read-only, and `resolve-conversation`, `remove-tag`, and\n`remove-custom-data` are marked destructive, so clients that surface those hints can warn you\nbefore running them. No tool is marked idempotent \u2014 calling one twice does the work twice.\n\n### The confirmation flow\n\nFive tools refuse to act until you approve. Instead of doing the work they return\n`confirmation_required: true` with a `confirmation_token`, an `affected_count`, a plain-language\n`message`, and `expires_in_seconds`. The assistant shows you the message, then repeats the call\nwith the token to proceed.\n\nTokens last **300 seconds** and are bound to the exact arguments they were issued for, so an\napproval cannot be replayed against a different call.\n\n| Tool | Asks when |\n| --- | --- |\n| `resolve-conversation` | Always \u2014 show the user the `message`, then retry with `confirmation_token` |\n| `unresolve-conversation` | Always |\n| `assign-conversation` | Always |\n| `remove-tag` | Always |\n| `remove-custom-data` | Always |\n\n---\n\n# Read tools\n\n## `list-conversations`\n\nLists conversations newest first, with a preview of the last message. Call this before reading\nmessages so newly created conversations are picked up.\n\n**Permission:** `read_conversations`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `status` | string | No | `all`, `unresolved`, or `resolved`. Defaults to `all`. |\n| `page` | integer | No | 1\u201310000. Defaults to `1`. |\n| `per_page` | integer | No | 1\u2013100. Defaults to `25`. |\n\n**Returns** `conversations` and `pagination`.\n\nEach conversation carries `id`, `contact` (`id`, `name`, `email`), `last_message` (`id`,\n`content`, `type`, `origin`, `sender_type`, `created_at`), `widget_id`, `origin`, `origin_url`,\n`email_subject`, `is_resolved`, `resolved_at`, `ended_at`, `created_at`, and `updated_at`.\n`pagination` carries `page`, `per_page`, `has_more`, and `next_page`.\n\n## `get-conversation`\n\nGets one conversation with contact and assigned-agent detail.\n\n**Permission:** `read_conversations`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `conversation_id` | string | Yes | UUID. |\n\n**Returns** a single `conversation` object with everything `list-conversations` provides plus\n`contact.phone`, `contact.country`, `contact.language`, `contact.timezone`, `assigned_agents`\n(each `id`, `name`, `email`), `message_count`, `social_account_identifier`,\n`external_identifier`, `resolved_by`, and `reopened_at`.\n\n**Errors:** no permission; `Conversation not found for the configured team.`\n\n## `list-conversation-messages`\n\nLists the messages in one conversation, newest first, using cursor pagination.\n\n**Permission:** `read_conversation_messages`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `conversation_id` | string | Yes | UUID. |\n| `limit` | integer | No | 1\u2013100. Defaults to `50`. |\n| `before_sort_number` | string | No | Cursor. Pass `next_before_sort_number` from the previous response. |\n| `include_system_messages` | boolean | No | Defaults to `false`. |\n| `include_internal_messages` | boolean | No | Defaults to `false`. |\n\n**Returns** `conversation_id`, `messages`, and `pagination`.\n\nEach message carries `id`, `conversation_id`, `sort_number`, `sender` (`type`, `id`, `name`,\n`email`), `origin`, `type`, `content`, `urls`, `parent_id`, `is_system_message`, `edited_at`,\n`created_at`, and `updated_at`. `pagination` carries `limit`, `has_more`, and\n`next_before_sort_number`.\n\nNote that system and internal notes are hidden unless you ask for them, so an assistant\nsummarising a thread sees what the visitor saw by default.\n\n## `search-conversations`\n\n**Permission:** `read_conversations`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `query` | string | Yes | 1\u2013255 characters. |\n| `limit` | integer | No | 1\u201350. Defaults to `20`. |\n\n**Returns** `conversations`, each with `id`, `email_subject`, `origin`, `is_resolved`, and\n`contact` (`id`, `name`, `email`). This is a lighter shape than `list-conversations` \u2014 follow up\nwith `get-conversation` for full detail.\n\n## `get-visitor`\n\n**Permission:** `read_visitor_details`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `visitor_id` | string | Yes | UUID. |\n\n**Returns** `visitor` with `id`, `name`, `email`, `phone`, `country`, `language`, `timezone`,\n`widget_id`, and `created_at`.\n\n**Errors:** no permission; `Visitor not found for the authorized sources.`\n\n## `search-contacts`\n\n**Permission:** `search_contacts`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `query` | string | Yes | 1\u2013255 characters. |\n| `limit` | integer | No | 1\u201350. Defaults to `20`. |\n\n**Returns** `contacts`, each with `id`, `name`, `email`, `phone`, and `widget_id`.\n\n## `search-knowledge-base`\n\nSearches your FAQ and Help Center content \u2014 useful for grounding a reply in your own material\ninstead of letting the model improvise.\n\n**Permission:** `search_knowledge_base`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `query` | string | Yes | 1\u2013255 characters. |\n| `limit` | integer | No | 1\u201350. Defaults to `20`. |\n\n**Returns** `results`, each with `id`, `question`, and `answer`.\n\n## `list-tags`\n\n**Permission:** `view_tags`\n\nTakes no parameters. **Returns** `tags`, each with `id`, `name`, and `color`.\n\n## `list-custom-fields`\n\n**Permission:** `view_custom_fields`\n\nTakes no parameters. **Returns** `custom_fields`, each with `id` and `name`.\n\n## `list-agents`\n\nLists teammates so the assistant can resolve a name like \"Nibir\" to an agent UUID before\nassigning. Deactivated agents are omitted.\n\n**Permission:** `assign_conversations`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `query` | string | No | Filter by name or email (partial match). |\n| `limit` | integer | No | Max results (default 50, max 100). |\n\n**Returns** `agents`, each with `id`, `name`, `email`, `status`, and `online_status`.\n\n---\n\n# Write tools\n\n## `send-message`\n\nSends a reply into a conversation. The message is posted as the connection's **Send Replies as**\nagent, so it appears to the visitor like any other agent reply.\n\n**Permission:** `send_replies`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `conversation_id` | string | Yes | UUID. |\n| `content` | string | Yes | 1\u201310,000 characters. |\n\n**Returns** `message` with `id`, `conversation_id`, `content`, `type`, and `created_at`.\n\n**Errors:** no permission; conversation not found; `No agent is configured for this connection.`;\nhuman handoff already requested for this conversation. Chatway also rejects sends that are not\nallowed for the conversation's current state, passing through its own explanation.\n\nAfter `handoff-to-human` (or Chatway AI's own handoff) has been requested, External AI cannot\nsend further replies on that conversation until the handoff is cleared.\n\n## `resolve-conversation`\n\n**Permission:** `resolve_conversations` \u00b7 **Confirmation:** always \u00b7 **Bulk queue:** when more than one conversation\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `conversation_ids` | array of string | Yes | 1\u2013100 UUIDs. Pass all targets in one call \u2014 do not loop single resolves. |\n| `confirmation_token` | string | No | Required on the second call after the user approves the challenge. |\n\n**Returns** `resolved_conversation_ids` for a single conversation. For two or more, returns\n`queued: true`, `queued_conversation_ids`, and `skipped_conversation_ids` \u2014 each conversation is\nprocessed in its own background job.\n\nThe first call always returns `confirmation_required: true` with a plain-language `message`, for\nexample:\n\n> This action will resolve 100 conversations. Are you sure?\n\nShow that message to the user. After they approve, call again with the same arguments plus\n`confirmation_token`.\n\n## `unresolve-conversation`\n\n**Permission:** `unresolve_conversations` \u00b7 **Confirmation:** always \u00b7 **Bulk queue:** when more than one conversation\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `conversation_ids` | array of string | Yes | 1\u2013100 UUIDs. |\n| `confirmation_token` | string | No | Required on the second call after the user approves the challenge. |\n\n**Returns** `unresolved_conversation_ids` for a single conversation. For two or more, returns\n`queued: true` with `queued_conversation_ids` and `skipped_conversation_ids` (one background job\nper conversation).\n\n## `assign-conversation`\n\nAssigns or unassigns a teammate. Prefer `agent_query` when the user names someone (\"assign\nNibir\"); use `list-agents` first if you need to browse the roster or the match is ambiguous.\n\n**Permission:** `assign_conversations` \u00b7 **Confirmation:** always \u00b7 **Bulk queue:** when more than one conversation\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `conversation_ids` | array of string | Yes | 1\u2013100 UUIDs. |\n| `agent_id` | string | One of | UUID of an agent on your team. Required unless `agent_query` is set. |\n| `agent_query` | string | One of | Name or email to resolve (e.g. `Nibir`). Required unless `agent_id` is set. |\n| `confirmation_token` | string | No | Required on the second call after the user approves the challenge. |\n\n**Returns** `agent_id`, `agent` (`id`, `name`, `email`), and `assigned_conversation_ids` for a\nsingle conversation. For two or more, returns `queued: true` with `queued_conversation_ids` and\n`skipped_conversation_ids` (one background job per conversation).\n\nWhen several teammates match `agent_query`, the tool returns `ambiguous: true` with a\n`candidates` list instead of assigning \u2014 call again with the chosen `agent_id`.\n\n**Errors:** no permission; `Agent not found for this team.`; no match for `agent_query`.\n\n## `add-note`\n\nAdds a private internal note. Notes are never shown to the visitor.\n\n**Permission:** `add_notes`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `conversation_id` | string | Yes | UUID. |\n| `content` | string | Yes | 1\u201310,000 characters. |\n\n**Returns** `note` with `id`, `conversation_id`, `content`, and `created_at`.\n\n**Errors:** no permission; conversation not found; `The authenticated user does not have an agent\nprofile.`\n\n## `add-tag`\n\nTags the visitor on a conversation. Creates the tag if it does not exist yet.\n\n**Permission:** `add_tags`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `conversation_id` | string | Yes | UUID. |\n| `name` | string | Yes | Up to 100 characters. |\n| `color` | string | No | Up to 50 characters. |\n\n**Returns** `conversation_id`, `chat_contact_id`, and `tag`.\n\n**Errors:** no permission; conversation not found; `This conversation has no visitor\/contact to\ntag.`\n\n## `remove-tag`\n\n**Permission:** `remove_tags` \u00b7 **Confirmation:** always\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `conversation_id` | string | Yes | UUID. |\n| `name` | string | Yes | Up to 100 characters. |\n| `confirmation_token` | string | No | Required on the second call. |\n\n**Returns** `conversation_id`, `chat_contact_id`, and `removed_tag`.\n\nEvery call is confirmed, even for a single tag:\n\n> This action will remove the tag \"refund\". Are you sure?\n\n## `add-custom-data`\n\nSets a custom field value on a visitor. Note this targets a **visitor**, not a conversation.\n\n**Permission:** `add_custom_data`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `visitor_id` | string | Yes | UUID. |\n| `name` | string | Yes | Up to 100 characters. |\n| `value` | string | Yes | Up to 1,000 characters. |\n\n**Returns** `visitor_id`, `name`, and `value`.\n\n## `update-custom-data`\n\nSame parameters and return shape as `add-custom-data`, for changing a value that already exists.\n\n**Permission:** `update_custom_data`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `visitor_id` | string | Yes | UUID. |\n| `name` | string | Yes | Up to 100 characters. |\n| `value` | string | Yes | Up to 1,000 characters. |\n\n**Returns** `visitor_id`, `name`, and `value`.\n\n## `remove-custom-data`\n\n**Permission:** `remove_custom_data` \u00b7 **Confirmation:** always\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `visitor_id` | string | Yes | UUID. |\n| `name` | string | Yes | Up to 100 characters. |\n| `confirmation_token` | string | No | Required on the second call. |\n\n**Returns** `visitor_id` and `removed_field`.\n\n## `handoff-to-human`\n\nEscalates a conversation to a human using the same handover flow as Chatway's built-in AI agent,\nso your team gets the notifications and inbox state they already expect.\n\n**Permission:** `request_human_handoff`\n\n| Parameter | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `conversation_id` | string | Yes | UUID. |\n\n**Returns** `conversation_id` and `status`, where `status` is `handoff_requested`.\n\n---\n\n## Common workflows\n\n**Triage the unresolved queue.** `list-conversations` with `status: unresolved`, then\n`list-conversation-messages` on each interesting one, then `add-tag` or `assign-conversation`\n(use `list-agents` or `agent_query` when assigning by name).\n\n**Answer from your own docs.** `list-conversation-messages` to read the question,\n`search-knowledge-base` to find the answer, `send-message` to reply.\n\n**Find a customer's history.** `search-contacts` to get the visitor, `get-visitor` for their\nprofile, `search-conversations` for their past threads.\n\n**Close out a batch.** `search-conversations` to gather candidates, `resolve-conversation` with\nall the IDs, then confirm when asked.\n\n## Related pages\n\n- [Permissions & access](\/mcp\/guides.mcp_permissions_and_access) \u2014 which permission unlocks which tool.\n- [MCP overview](\/mcp\/guides.mcp_overview) \u2014 how MCP compares to webhooks and the REST API.\n", "summary": "Tool reference", "security": [], "x-codeSamples": [], "x-chatway-docs-section": "mcp" } }, "guides.mcp_permissions_and_access": { "post": { "operationId": "guides.mcp_permissions_and_access", "description": "# Permissions & access\n\nEvery MCP request passes three independent checks. All three must pass, so a permission on its\nown is never enough to reach data you did not share.\n\n| Layer | Question |\n| --- | --- |\n| Widgets & channels | Is this conversation in an inbox the connection can access? |\n| Permissions | Was this specific capability granted to the connection? |\n| Role | Does the authorizing user's Chatway role allow it at all? |\n\nTools whose permission was not granted are not offered to the assistant, and return an error if\ncalled anyway. The [Tool reference](\/mcp\/guides.mcp_tool_reference) documents what each tool\ntakes and returns.\n\n## Widgets & channels\n\nA connection is scoped to the widgets and channels you picked when authorizing it. All of them\nare selected by default, and you can narrow the list at any time.\n\nChannels cover email, WhatsApp, Messenger, and Instagram, so you can give an assistant your\nwebsite widget without also giving it your WhatsApp inbox.\n\nAnything outside the selection is invisible: conversations from other widgets are not listed, not\nsearchable, and cannot be fetched by ID. Team boundaries are enforced separately and cannot be\nwidened by any permission \u2014 a connection never reaches another team's data.\n\nYou must keep at least one widget or channel selected.\n\n## Read permissions\n\n| Permission | Grants | Unlocks |\n| --- | --- | --- |\n| `read_conversations` | View conversations and conversation lists. | `list-conversations`, `get-conversation`, `search-conversations` |\n| `read_conversation_messages` | View conversations and all messages. | `list-conversation-messages` |\n| `read_visitor_details` | View visitor profile and activity. | `get-visitor` |\n| `search_contacts` | Search and view contact information. | `search-contacts` |\n| `search_knowledge_base` | Search FAQs and Help Center content. | `search-knowledge-base` |\n| `view_tags` | View tags and their details. | `list-tags` |\n| `view_custom_fields` | View custom fields and values. | `list-custom-fields` |\n\nAt least one of `read_conversations` or `read_conversation_messages` is always required \u2014 an\nassistant that cannot read anything has nothing to act on.\n\n## Write permissions\n\n| Permission | Grants | Unlocks |\n| --- | --- | --- |\n| `send_replies` | Send messages as an agent. | `send-message` |\n| `resolve_conversations` | Mark conversations as resolved. | `resolve-conversation` |\n| `unresolve_conversations` | Reopen conversations. | `unresolve-conversation` |\n| `assign_conversations` | Assign conversations to agents. | `list-agents`, `assign-conversation` |\n| `add_notes` | Add private notes to conversations. | `add-note` |\n| `add_tags` | Add tags to conversations or contacts. | `add-tag` |\n| `remove_tags` | Remove tags from conversations or contacts. | `remove-tag` |\n| `add_custom_data` | Add custom field values. | `add-custom-data` |\n| `update_custom_data` | Update custom field values. | `update-custom-data` |\n| `remove_custom_data` | Remove custom field values. | `remove-custom-data` |\n| `request_human_handoff` | Trigger handover to a human agent. | `handoff-to-human` |\n\n## Roles\n\nOnly **owners and admins** may connect or reconnect an External AI assistant (the MCP OAuth\nflow). **Members** do not see **AI \u2192 External AI** in Settings \u2014 they cannot view connections,\nauthorize from an MCP client, or change External AI settings.\n\nWhen an owner or admin authorizes, they may grant read and write permissions according to their\nrole:\n\n| Role | Can connect (OAuth) | Can grant |\n| --- | --- | --- |\n| Owner | Yes | Read and write |\n| Admin | Yes | Read and write |\n| Member | No | \u2014 |\n\nConnections are **shared per team**: one row per assistant client (Claude, Cursor, and so on) in\n**AI \u2192 External AI**, visible only to **owners and admins**. Only they can rename, change access,\nor disconnect from the dashboard.\n\n## Who actions are attributed to\n\nEvery write action from External AI is attributed to the **Send Replies as** agent on the\nconnection \u2014 not the person who authorized OAuth. That covers `send-message`, notes, resolve,\nunresolve, assign (\"by \u2026\"), and related system messages.\n\nYou choose the agent when authorizing, and it defaults to whoever created the connection. Your\nteam sees that agent's name in the inbox, and visitor-facing replies appear like any other agent\nreply. Change it any time under **Manage access** if you would rather actions come from a\ndedicated \"AI assistant\" teammate.\n\nMessages are limited to 10,000 characters.\n\n## Confirmation on bulk and destructive actions\n\nHigh-risk actions are safe by default. Rather than acting immediately, the tool returns a\nchallenge and the assistant must ask you before continuing:\n\n> This action will resolve 100 conversations. Are you sure?\n\nThe assistant then repeats the call with the `confirmation_token` from the challenge. Tokens\nexpire after 5 minutes and are tied to that exact call, so one cannot be reused to approve a\ndifferent action.\n\n| Tool | Needs confirmation |\n| --- | --- |\n| `resolve-conversation` | Always |\n| `unresolve-conversation` | Always |\n| `assign-conversation` | Always |\n| `remove-tag` | Always |\n| `remove-custom-data` | Always |\n\nBulk conversation actions are capped at 100 conversations per call. When more than one\nconversation is targeted, each runs in its own background job after confirmation. See the\n[Tool reference](\/mcp\/guides.mcp_tool_reference) for the confirmation payload and each tool's\nexact limits.\n\n## Choosing a permission set\n\nStart read-only. Grant `read_conversations` and `read_conversation_messages`, confirm the\nassistant behaves the way you expect, then add write permissions one group at a time.\n\nIf you only want an assistant to help you triage, read permissions plus `add_notes` and\n`add_tags` are usually enough \u2014 it can summarise and organise without ever messaging a visitor.\n\n## Changing permissions later\n\nNothing is fixed at connect time. Edit a connection to add or remove permissions, change its\nwidgets and channels, or switch the replying agent \u2014 the client does not need to reconnect or\nre-authorize. Changes apply to the assistant's next request, and removing a permission takes\neffect immediately.\n\nSee [Manage connections](\/mcp\/guides.mcp_manage_connections).\n", "summary": "Permissions & access", "security": [], "x-codeSamples": [], "x-chatway-docs-section": "mcp" } }, "guides.mcp_manage_connections": { "post": { "operationId": "guides.mcp_manage_connections", "description": "# Manage connections\n\nEvery assistant that completed the OAuth flow is listed in Chatway under **AI \u2192 External AI**\nfor **owners and admins**. From there they can review what each one can do, change its access,\nwatch what it has been doing, and cut it off.\n\n## What a connection shows\n\n| Field | Meaning |\n| --- | --- |\n| Assistant | The detected client, such as Claude, ChatGPT, Cursor, or VS Code |\n| Connection name | The name you gave it when authorizing, so you can tell similar clients apart |\n| Status | `Connected` or `Disconnected` |\n| Widgets & channels | The inboxes this connection can reach |\n| Permissions | The read and write capabilities it was granted |\n| Reply as | The agent that replies and other write actions are attributed to |\n| Connected | When the connection was authorized |\n| Last used | When the assistant last called a tool |\n\n## Statuses\n\n| Status | Meaning |\n| --- | --- |\n| Connected | The token is live and the assistant can call tools. |\n| Disconnected | Access has been revoked. The record is kept so you keep the history. |\n\n## Manage access\n\n**Manage access** opens everything chosen during sign-in. Only **owners and admins** can open and\nedit a connection.\n\nEditable settings:\n\n- Rename the connection\n- Add or remove widgets and channels\n- Add or remove read and write permissions\n- Change which agent replies and other write actions are attributed to\n\nChanges apply to the assistant's next request. The client does **not** need to reconnect or\nre-authorize, and removing a permission or a widget takes effect immediately.\n\nTwo rules still hold when editing: at least one widget or channel must stay selected, and at\nleast one read permission must remain. Write permissions can only be granted by an owner or\nadmin \u2014 see [Permissions & access](\/mcp\/guides.mcp_permissions_and_access).\n\n## Latest activity\n\nEach connection keeps its own audit log of the tools it has called, what they targeted, and when.\nUse it to answer \"why did this conversation get resolved?\" or to confirm an assistant is only\ndoing what you expect before you widen its permissions.\n\nBecause replies are posted as a real agent, messages an assistant sends are also visible in the\ninbox like any other reply.\n\n## Usage and limits\n\nEach connection is limited to **120 requests per minute**, counted separately per connection, so\none busy assistant cannot slow down another. The connection view shows how much of that budget\nis in use.\n\nSustained `429` responses on a single connection mean that assistant is polling too aggressively.\nIt is not a workspace-wide problem and does not affect your other connections or the REST API.\n\n## Multiple connections\n\nYou can connect more than one assistant at a time \u2014 for example Claude for triage and Cursor for\ndevelopment \u2014 and each **client type** gets its own token, widgets and channels, permissions, and\nusage budget on your team.\n\nThere is **one connection per assistant client per team** (one Claude, one Cursor, and so on).\nUse the **connection name** to tell similar setups apart when you use multiple custom integrations.\n\nOnly **owners and admins** see **AI \u2192 External AI** in Settings. They can connect, reconnect,\nchange, or disconnect assistants there. **Members** do not have that menu and cannot complete MCP\nOAuth or edit connection settings.\n\n## Disconnect\n\nDisconnecting asks you to confirm, then revokes the access token straight away. Only owners and\nadmins can disconnect from **AI \u2192 External AI**. The assistant\nloses access mid-session and its next request fails with `401`. The connection stays in the list\nas `Disconnected` so you keep the audit trail.\n\nReconnecting the same client starts a fresh OAuth flow and issues a new token \u2014 the old one is\nnever reinstated.\n\n## When access ends without you doing anything\n\n- The team member whose token was issued is deactivated or removed from the team (their MCP token\n stops working; an owner or admin may reconnect for the team).\n- Every widget and channel the connection pointed at has been deleted.\n\nIn both cases the assistant's requests start failing rather than silently falling back to wider\naccess.\n\n## Real-time replies\n\nThe External AI page also shows whether webhooks are set up, since that is what lets your agent\nanswer visitors automatically instead of only when you ask it to. If you have no webhook yet the\npage offers to create one; if you do, it links you to it.\n\nWebhooks and MCP are independent \u2014 disconnecting an assistant does not stop your webhooks, and\ndeleting a webhook does not affect MCP access. See the\n[MCP overview](\/mcp\/guides.mcp_overview) for how the two fit together, and **Webhook docs \u2192\nOverview** in the sidebar for setup.\n", "summary": "Manage connections", "security": [], "x-codeSamples": [], "x-chatway-docs-section": "mcp" } }, "guides.webhooks_overview": { "post": { "operationId": "guides.webhooks_overview", "description": "# Webhooks overview\n\nThis document provides detailed technical information for developers integrating with Chatway Webhooks, including event schemas, delivery behavior, security, retries, and best practices.\n\nChatway Webhooks are available on all plans, including the Free plan.\n\nChatway sends HTTP **POST** requests to your configured HTTPS endpoint when a subscribed event occurs.\n\n- Webhooks are **event-driven**, **near real-time**, and use **at-least-once delivery**.\n- Configure webhooks from the Chatway app under **Settings \u2192 Developer Tools \u2192 Webhooks**.\n- Your endpoint must respond with any **2xx** status within the configured timeout.\n\n### Replying to a visitor message\n\nFor the full end-to-end tutorial (subscribe to `message.received`, verify the signature, read `data.conversation.id`, and call **POST \/messages**), start with **Quickstart \u2192 Receive a message and send a reply** in the sidebar.\n\n## Endpoint requirements\n\n| Requirement | Value |\n|---|---|\n| Supported protocol | `HTTPS` only |\n| Request method | `POST` |\n| Expected response | Any `2xx` HTTP status code acknowledges receipt. `5xx`, timeouts, and network errors are retried; most `4xx` responses (including `410`) are not. |\n| Redirects | Not followed. Your endpoint must respond directly (no `3xx` redirect chain). |\n| Network targets | Public HTTPS endpoints only. Private, loopback, and link-local addresses (for example `127.0.0.1`, `10.0.0.0\/8`, `169.254.169.254`) are blocked at delivery time. |\n\n## Request headers\n\nEvery webhook request includes the following headers:\n\n```\nContent-Type: application\/json\nX-Chatway-Event: message.received\nX-Chatway-Webhook-Id: 9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b\nX-Chatway-Delivery-Id: del_456\nX-Chatway-Delivery-Attempt: 1\nX-Chatway-Timestamp: 1785933000\nX-Chatway-Signature: sha256=3c9f5e...\n```\n\n| Header | Description |\n|---|---|\n| `X-Chatway-Event` | Event name (for example, `message.received`) |\n| `X-Chatway-Webhook-Id` | Unique webhook subscription ID |\n| `X-Chatway-Delivery-Id` | Unique ID for this HTTP delivery attempt (`del_\u2026`). A new value is sent on each retry. |\n| `X-Chatway-Delivery-Attempt` | Attempt number for this event (`1` on first try, then `2`, `3`, \u2026 up to 4). Sent as a decimal string in the header. |\n| `X-Chatway-Timestamp` | Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header. Use with signature verification to limit replay attacks. |\n| `X-Chatway-Signature` | HMAC SHA256 of `{timestamp}.{raw_request_body}` |\n\n## Signature verification\n\nChatway signs each request using **HMAC SHA256**.\n\n### Signature generation\n\n```\nsigned_payload = timestamp + \".\" + raw_request_body\nHMAC_SHA256(secret, signed_payload)\n```\n\nThe header value is prefixed with `sha256=`. The timestamp is the value of `X-Chatway-Timestamp`.\n\n### Verification steps\n\n1. Read the raw request body before JSON parsing.\n2. Extract `X-Chatway-Signature` and `X-Chatway-Timestamp`.\n3. Reject requests whose timestamp is older than 300 seconds (recommended).\n4. Compute HMAC SHA256 over `{timestamp}.{raw_body}` using your webhook secret.\n5. Compare using a constant-time comparison.\n\n### Example (Node.js + Express)\n\n```javascript\nconst crypto = require(\"crypto\");\nconst express = require(\"express\");\n\nconst app = express();\n\n\/\/ Preserve raw body for signature verification (required).\napp.post(\n \"\/webhooks\/chatway\",\n express.raw({ type: \"application\/json\" }),\n (req, res) => {\n const secret = process.env.CHATWAY_WEBHOOK_SECRET;\n const signature = req.headers[\"x-chatway-signature\"];\n const timestamp = req.headers[\"x-chatway-timestamp\"];\n const rawBody = req.body; \/\/ Buffer\n\n if (!verifyChatwaySignature(rawBody, signature, timestamp, secret)) {\n return res.status(401).send(\"Invalid signature\");\n }\n\n res.status(200).send(\"ok\");\n },\n);\n\nfunction verifyChatwaySignature(rawBody, signatureHeader, timestampHeader, secret) {\n if (!signatureHeader || !timestampHeader || !secret) {\n return false;\n }\n\n const timestamp = Number(timestampHeader);\n if (!Number.isFinite(timestamp)) {\n return false;\n }\n\n const toleranceSeconds = 300;\n if (Math.abs(Math.floor(Date.now() \/ 1000) - timestamp) > toleranceSeconds) {\n return false;\n }\n\n const signedPayload = `${timestamp}.${rawBody.toString(\"utf8\")}`;\n const expected = crypto.createHmac(\"sha256\", secret).update(signedPayload).digest(\"hex\");\n const expectedHeader = `sha256=${expected}`;\n\n const expectedBuffer = Buffer.from(expectedHeader);\n const actualBuffer = Buffer.from(signatureHeader);\n\n if (expectedBuffer.length !== actualBuffer.length) {\n return false;\n }\n\n return crypto.timingSafeEqual(expectedBuffer, actualBuffer);\n}\n```\n\n### Example (PHP)\n\n```\nfunction verifyChatwaySignature(\n string $rawBody,\n ?string $signatureHeader,\n ?string $timestampHeader,\n string $secret,\n int $toleranceSeconds = 300\n): bool {\n if ($signatureHeader === null || $signatureHeader === '' || $timestampHeader === null || $timestampHeader === '') {\n return false;\n }\n\n $timestamp = filter_var($timestampHeader, FILTER_VALIDATE_INT);\n if ($timestamp === false) {\n return false;\n }\n\n if (abs(time() - $timestamp) > $toleranceSeconds) {\n return false;\n }\n\n $signedPayload = $timestamp.'.'.$rawBody;\n $expected = 'sha256='.hash_hmac('sha256', $signedPayload, $secret);\n\n return hash_equals($expected, $signatureHeader);\n}\n\n\/\/ Laravel example\n$rawBody = $request->getContent();\n$signature = $request->header('X-Chatway-Signature');\n$timestamp = $request->header('X-Chatway-Timestamp');\n$secret = config('services.chatway.webhook_secret');\n\nif (! verifyChatwaySignature($rawBody, $signature, $timestamp, $secret)) {\n abort(401, 'Invalid webhook signature.');\n}\n```\n\n## Event payload structure\n\nAll webhook payloads share a common envelope:\n\n```json\n{\n \"id\": \"evt_1234567890abcdef1234567890abcdef\",\n \"event\": \"message.received\",\n \"data\": {\n \"message\": {\n \"id\": \"679f5ba4-3cbf-42eb-86dc-63566cec6b58\",\n \"content\": \"Hello, I need help\",\n \"attachments\": [],\n \"created_at\": \"2026-02-04T10:31:12Z\"\n },\n \"conversation\": {\n \"id\": \"750c42a1-1ce1-40ae-beba-4cc66f2b1023\",\n \"channel\": \"website\",\n \"status\": \"open\",\n \"widget_name\": \"Main site widget\",\n \"identifier\": \"wdg_abc123\"\n },\n \"visitor\": {\n \"id\": \"bfc39f4b-e8aa-4e1c-8e6a-162a5d869702\",\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"phone\": \"+1XXXXXXXXXX\"\n }\n },\n \"occurred_at\": \"2026-02-04T10:31:12Z\",\n \"version\": \"2026-09\"\n}\n```\n\n| Field | Type | Description |\n|---|---|---|\n| `id` | string | Stable event ID (`evt_\u2026`). Same value on every retry for this notification. |\n| `event` | string | Event name |\n| `data` | object | Event-specific payload documented on each webhook below. |\n| `occurred_at` | ISO 8601 | Event timestamp |\n| `version` | string | Payload version (`2026-09`) |\n\n## Field reference\n\nCommon types, optional fields, and normalized channel values used across events.\n\n### Envelope\n\n| Field | Type | Notes |\n|---|---|---|\n| `id` | string | Stable event ID (evt_\u2026). Identical across HTTP retries for the same notification to your endpoint. Use for idempotent processing. |\n| `event` | string | Event name (for example message.received). |\n| `data` | object | Event-specific payload. |\n| `occurred_at` | string (ISO 8601) | When the business event occurred. Stable across retries for a given id. |\n| `version` | string | Payload schema version. |\n\n### Conversation\n\n| Field | Type | Notes |\n|---|---|---|\n| `id` | string (UUID) | Conversation ID. |\n| `channel` | string | Normalized channel: website, email, messenger, whatsapp, fb, instagram. |\n| `status` | string | open or resolved. |\n| `widget_name` | string (optional) | Present when the conversation is tied to a website widget. |\n| `identifier` | string (optional) | Widget identifier when widget_name is present. |\n| `resolved_at` | string (ISO 8601) (optional) | Present on conversation.resolved when status is resolved. |\n| `created_at` | string (ISO 8601) (optional) | Present on conversation.created. |\n| `first_page_url` | string (optional) | Present on conversation.created when available. |\n\n### Agent\n\n| Field | Type | Notes |\n|---|---|---|\n| `id` | string (UUID) | Agent ID. |\n| `name` | string | Agent display name. |\n| `email` | string (optional) | Agent email when available. Used on agent.assigned, conversation.resolved, and message.sent. |\n\n### Visitor contact\n\n| Field | Type | Notes |\n|---|---|---|\n| `id` | string (UUID) | Visitor\/contact ID. |\n| `name` | string | null (optional) | Omitted when empty. |\n| `email` | string | null | Always present on visitor; null when unknown. |\n| `phone` | string | null | Always present on visitor; null when unknown. |\n\n### Contact source\n\n| Field | Type | Notes |\n|---|---|---|\n| `source` | string | Page URL when the visitor came from the widget (for example https:\/\/example.com\/pricing), or a normalized channel label (email, messenger, whatsapp, fb) for integrated channels. |\n\n### Assigned by\n\n| Field | Type | Notes |\n|---|---|---|\n| `assigned_by` | object | Who performed the action. Contains exactly one of: agent (id, name, email), automation (id UUID, name), or system (empty object). Used on tag.assigned, custom.data.assigned, and agent.assigned. |\n\n### Removed by\n\n| Field | Type | Notes |\n|---|---|---|\n| `removed_by` | object | Same shape as assigned_by. Who removed the tag or custom data: agent, automation (id UUID, name), or system (empty object). Used on tag.removed and custom.data.removed. |\n\n### Resolved by\n\n| Field | Type | Notes |\n|---|---|---|\n| `resolved_by` | object | Same shape as assigned_by. Who resolved the conversation: agent, automation (id UUID, name), or system (empty object). Used on conversation.resolved. |\n\n### Message\n\n| Field | Type | Notes |\n|---|---|---|\n| `content` | string (optional) | Message text. May be omitted when attachments are present. |\n| `attachments` | array | Zero or more attachment objects (see below). |\n\n### Attachment\n\n| Field | Type | Notes |\n|---|---|---|\n| `content` | string (URL) | Public URL of the file. |\n| `type` | string (optional) | Logical type (for example image, file, video). |\n| `mime` | string (optional) | MIME type when known. |\n| `original_file_name` | string (optional) | Original filename when available. |\n| `size` | integer | null (optional) | Size in bytes when known. |\n\n### Contact updated\n\n| Field | Type | Notes |\n|---|---|---|\n| `previous_values` | object | Map of field names to values before the update. Only includes keys listed in updated_fields. |\n| `current_values` | object | Map of field names to values after the update. |\n\n### Custom data\n\n| Field | Type | Notes |\n|---|---|---|\n| `custom_data` | object | Single key\/value pair for custom.data.assigned and custom.data.removed. Values are strings or JSON-serializable scalars; complex objects may appear depending on how the field was stored. |\n\n### Limits\n\n| Field | Type | Notes |\n|---|---|---|\n| `attachment URLs` | string (optional) | Up to 2048 characters per URL (aligned with upload validation). |\n| `attachments per message` | integer (optional) | Typically up to 9 files per message in the product UI. |\n\n## Idempotency & retries\n\n- Use the envelope field `id` (`evt_\u2026`) to detect duplicate processing of the same business event. It stays the same across HTTP retries to your endpoint.\n- `X-Chatway-Delivery-Id` identifies a single HTTP attempt (`del_\u2026`) and changes on each retry.\n- `X-Chatway-Delivery-Attempt` is the attempt counter (`1` through `4`).\n- `occurred_at` in the JSON body is fixed when the event is first dispatched and does not change on retry.\n\n## Timeout & processing requirements\n\nChatway enforces a strict **4-second timeout** for webhook deliveries. If your endpoint does not respond within 4 seconds, the delivery is marked as failed and retried according to the retry policy.\n\n## Delivery & retry policy\n\n### Retry conditions\n\n- Timeout\n- Network error\n- HTTP `5xx` response\n\n### No retry\n\n- HTTP `4xx` responses (including `410 Gone`) are not retried for that delivery attempt.\n- Returning `410` does not automatically disable your webhook subscription; turn it off in **Settings \u2192 Developer Tools \u2192 Webhooks** if needed.\n\n### Retry schedule\n\n1. Immediate\n2. +1 minute\n3. +5 minutes\n4. +15 minutes\n\nChatway makes up to **4** delivery attempts. After the final failure, the delivery is marked as failed.\n\n## Required behavior\n\n- Respond immediately with a `2xx` HTTP status code.\n- Do not perform heavy processing before sending the response.\n- Acknowledge receipt first, then process the payload asynchronously.\n- Verify `X-Chatway-Signature` and `X-Chatway-Timestamp` on every request.\n- Handle duplicate deliveries idempotently using the envelope `id` field (`evt_\u2026`), not `X-Chatway-Delivery-Id`.", "summary": "Overview", "security": [], "x-codeSamples": [] } }, "conversation.created": { "post": { "operationId": "webhook.conversation_created", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nA new chat has started.", "summary": "Conversation created", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "conversation.created" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "conversation.created", "data": { "conversation": { "id": "750c42a1-1ce1-40ae-beba-4cc66f2b1023", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123", "created_at": "2026-02-04T10:30:00Z", "first_page_url": "https:\/\/example.com\/pricing" }, "visitor": { "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX", "country": "US", "ip": "203.0.113.10", "first_page_url": "https:\/\/example.com\/pricing" } }, "occurred_at": "2026-02-04T10:30:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `conversation.created`." }, "data": { "type": "object", "description": "Payload for conversation.created.", "examples": [ { "conversation": { "id": "750c42a1-1ce1-40ae-beba-4cc66f2b1023", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123", "created_at": "2026-02-04T10:30:00Z", "first_page_url": "https:\/\/example.com\/pricing" }, "visitor": { "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX", "country": "US", "ip": "203.0.113.10", "first_page_url": "https:\/\/example.com\/pricing" } } ], "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." }, "created_at": { "type": "string", "format": "date-time" }, "first_page_url": { "type": "string" } }, "required": [ "id", "channel", "status" ] }, "visitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Visitor\/contact ID." }, "name": { "type": "string", "description": "Visitor name. Omitted when empty." }, "email": { "type": [ "string", "null" ], "description": "Visitor email. Always present; null when unknown." }, "phone": { "type": [ "string", "null" ], "description": "Visitor phone. Always present; null when unknown." } }, "required": [ "id", "email", "phone" ] } }, "required": [ "conversation", "visitor" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeConversationCreated" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "message.received": { "post": { "operationId": "webhook.message_received", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nA visitor sent a new message.\n\n> Triggered only for visitor messages.", "summary": "Message received", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "message.received" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "message.received", "data": { "message": { "id": "679f5ba4-3cbf-42eb-86dc-63566cec6b58", "content": "Hello, I need help", "attachments": [ { "content": "https:\/\/cdn.example.com\/files\/invoice.pdf", "type": "file", "mime": "application\/pdf", "original_file_name": "invoice.pdf", "size": 204800 } ], "created_at": "2026-02-04T10:31:12Z" }, "conversation": { "id": "750c42a1-1ce1-40ae-beba-4cc66f2b1023", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" } }, "occurred_at": "2026-02-04T10:31:12Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `message.received`." }, "data": { "type": "object", "description": "Payload for message.received.", "examples": [ { "message": { "id": "679f5ba4-3cbf-42eb-86dc-63566cec6b58", "content": "Hello, I need help", "attachments": [ { "content": "https:\/\/cdn.example.com\/files\/invoice.pdf", "type": "file", "mime": "application\/pdf", "original_file_name": "invoice.pdf", "size": 204800 } ], "created_at": "2026-02-04T10:31:12Z" }, "conversation": { "id": "750c42a1-1ce1-40ae-beba-4cc66f2b1023", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" } } ], "properties": { "message": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID." }, "content": { "type": "string", "description": "Message text. May be omitted when attachments are present." }, "attachments": { "type": "array", "description": "Zero or more attachment objects. Each item has `content` (URL), optional `type`, `mime`, `original_file_name`, and `size` (bytes)\u2014see Webhooks overview \u2192 Field reference \u2192 Attachment.", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "Public URL of the file (up to 2048 characters)." }, "type": { "type": "string", "description": "Logical type (for example image, file, video)." }, "mime": { "type": "string", "description": "MIME type when known." }, "original_file_name": { "type": "string", "description": "Original filename when available." }, "size": { "type": [ "integer", "null" ], "description": "Size in bytes when known." } }, "required": [ "content" ] } }, "created_at": { "type": "string", "format": "date-time", "description": "When the message was created." } }, "required": [ "id", "attachments", "created_at" ] }, "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." } }, "required": [ "id", "channel", "status" ] }, "visitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Visitor\/contact ID." }, "name": { "type": "string", "description": "Visitor name. Omitted when empty." }, "email": { "type": [ "string", "null" ], "description": "Visitor email. Always present; null when unknown." }, "phone": { "type": [ "string", "null" ], "description": "Visitor phone. Always present; null when unknown." } }, "required": [ "id", "email", "phone" ] } }, "required": [ "message", "conversation", "visitor" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeMessageReceived" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "message.sent": { "post": { "operationId": "webhook.message_sent", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nAn agent sent a new message.\n\n> Triggered when an agent sends a message from the dashboard or API (including POST \/messages).\n\n> Internal notes, reminders, and system messages are not included.\n\n> `data.agent` is always present on this event. Dashboard sends use the signed-in agent. API sends use the `agent_id` on the stored message (include `agent_id` in POST \/messages for agent-originated replies).", "summary": "Message sent", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "message.sent" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "message.sent", "data": { "message": { "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde", "content": "Happy to help! Let me look into that for you.", "attachments": [], "created_at": "2026-02-04T10:32:00Z" }, "conversation": { "id": "750c42a1-1ce1-40ae-beba-4cc66f2b1023", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "agent": { "id": "0fbcf0f5-973a-4d6a-a1be-d777b6b2f69a", "name": "Sarah Chen", "email": "sarah@example.com" } }, "occurred_at": "2026-02-04T10:32:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `message.sent`." }, "data": { "type": "object", "description": "Payload for message.sent.", "examples": [ { "message": { "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde", "content": "Happy to help! Let me look into that for you.", "attachments": [], "created_at": "2026-02-04T10:32:00Z" }, "conversation": { "id": "750c42a1-1ce1-40ae-beba-4cc66f2b1023", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "agent": { "id": "0fbcf0f5-973a-4d6a-a1be-d777b6b2f69a", "name": "Sarah Chen", "email": "sarah@example.com" } } ], "properties": { "message": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID." }, "content": { "type": "string", "description": "Message text. May be omitted when attachments are present." }, "attachments": { "type": "array", "description": "Zero or more attachment objects. Each item has `content` (URL), optional `type`, `mime`, `original_file_name`, and `size` (bytes)\u2014see Webhooks overview \u2192 Field reference \u2192 Attachment.", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "Public URL of the file (up to 2048 characters)." }, "type": { "type": "string", "description": "Logical type (for example image, file, video)." }, "mime": { "type": "string", "description": "MIME type when known." }, "original_file_name": { "type": "string", "description": "Original filename when available." }, "size": { "type": [ "integer", "null" ], "description": "Size in bytes when known." } }, "required": [ "content" ] } }, "created_at": { "type": "string", "format": "date-time", "description": "When the message was created." } }, "required": [ "id", "attachments", "created_at" ] }, "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." } }, "required": [ "id", "channel", "status" ] }, "visitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Visitor\/contact ID." }, "name": { "type": "string", "description": "Visitor name. Omitted when empty." }, "email": { "type": [ "string", "null" ], "description": "Visitor email. Always present; null when unknown." }, "phone": { "type": [ "string", "null" ], "description": "Visitor phone. Always present; null when unknown." } }, "required": [ "id", "email", "phone" ] }, "agent": { "type": "object", "description": "Agent who sent the message. Always present on message.sent (dashboard agent or POST \/messages `agent_id`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent ID." }, "name": { "type": "string", "description": "Agent display name." }, "email": { "type": "string", "description": "Agent email when available." } }, "required": [ "id", "name" ] } }, "required": [ "message", "conversation", "visitor", "agent" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeMessageSent" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "message.updated": { "post": { "operationId": "webhook.message_updated", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nA chat message was edited.\n\n> Triggered when message content or attachments change after an edit from the agent or visitor app.\n\n> Internal notes and reminders are not included.", "summary": "Message updated", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "message.updated" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "message.updated", "data": { "message": { "id": "679f5ba4-3cbf-42eb-86dc-63566cec6b58", "content": "Hello, I need help with my order", "attachments": [], "created_at": "2026-02-04T10:31:12Z", "edited_at": "2026-02-04T10:35:00Z" }, "updated_fields": [ "content" ], "previous_values": { "content": "Hello, I need help" }, "conversation": { "id": "750c42a1-1ce1-40ae-beba-4cc66f2b1023", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" } }, "occurred_at": "2026-02-04T10:31:12Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `message.updated`." }, "data": { "type": "object", "description": "Payload for message.updated.", "examples": [ { "message": { "id": "679f5ba4-3cbf-42eb-86dc-63566cec6b58", "content": "Hello, I need help with my order", "attachments": [], "created_at": "2026-02-04T10:31:12Z", "edited_at": "2026-02-04T10:35:00Z" }, "updated_fields": [ "content" ], "previous_values": { "content": "Hello, I need help" }, "conversation": { "id": "750c42a1-1ce1-40ae-beba-4cc66f2b1023", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" } } ], "properties": { "message": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID." }, "content": { "type": "string", "description": "Message text. May be omitted when attachments are present." }, "attachments": { "type": "array", "description": "Zero or more attachment objects. Each item has `content` (URL), optional `type`, `mime`, `original_file_name`, and `size` (bytes)\u2014see Webhooks overview \u2192 Field reference \u2192 Attachment.", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "Public URL of the file (up to 2048 characters)." }, "type": { "type": "string", "description": "Logical type (for example image, file, video)." }, "mime": { "type": "string", "description": "MIME type when known." }, "original_file_name": { "type": "string", "description": "Original filename when available." }, "size": { "type": [ "integer", "null" ], "description": "Size in bytes when known." } }, "required": [ "content" ] } }, "created_at": { "type": "string", "format": "date-time", "description": "When the message was created." }, "edited_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "attachments", "created_at" ] }, "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." } }, "required": [ "id", "channel", "status" ] }, "visitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Visitor\/contact ID." }, "name": { "type": "string", "description": "Visitor name. Omitted when empty." }, "email": { "type": [ "string", "null" ], "description": "Visitor email. Always present; null when unknown." }, "phone": { "type": [ "string", "null" ], "description": "Visitor phone. Always present; null when unknown." } }, "required": [ "id", "email", "phone" ] }, "updated_fields": { "type": "array", "items": { "type": "string" } }, "previous_values": { "type": "object", "description": "Map of changed field names to values before the update." } }, "required": [ "message", "conversation", "visitor", "updated_fields", "previous_values" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeMessageUpdated" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "contact.created": { "post": { "operationId": "webhook.contact_created", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nA new contact was added or identified.", "summary": "Contact created", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "contact.created" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "contact.created", "data": { "contact": { "id": "con_123", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX", "source": "https:\/\/example.com\/pricing", "created_at": "2026-02-04T10:30:00Z" }, "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" } }, "occurred_at": "2026-02-04T10:30:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `contact.created`." }, "data": { "type": "object", "description": "Payload for contact.created.", "examples": [ { "contact": { "id": "con_123", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX", "source": "https:\/\/example.com\/pricing", "created_at": "2026-02-04T10:30:00Z" }, "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" } } ], "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "source": { "type": "string", "description": "Page URL or normalized channel label." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "email", "phone" ] }, "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." } }, "required": [ "id", "channel", "status" ] } }, "required": [ "contact", "conversation" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeContactCreated" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "contact.updated": { "post": { "operationId": "webhook.contact_updated", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nAn existing contact was updated.", "summary": "Contact updated", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "contact.updated" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "contact.updated", "data": { "contact": { "id": "con_123", "name": "John Doe", "email": "john.new@example.com", "phone": "+1XXXXXXXXXX" }, "updated_fields": [ "email" ], "previous_values": { "email": "john@example.com" }, "current_values": { "email": "john.new@example.com" } }, "occurred_at": "2026-02-04T10:30:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `contact.updated`." }, "data": { "type": "object", "description": "Payload for contact.updated.", "examples": [ { "contact": { "id": "con_123", "name": "John Doe", "email": "john.new@example.com", "phone": "+1XXXXXXXXXX" }, "updated_fields": [ "email" ], "previous_values": { "email": "john@example.com" }, "current_values": { "email": "john.new@example.com" } } ], "properties": { "contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "source": { "type": "string", "description": "Page URL or normalized channel label." } }, "required": [ "id", "name", "email", "phone" ] }, "updated_fields": { "type": "array", "items": { "type": "string" } }, "previous_values": { "type": "object", "description": "Map of field names to values before the update." }, "current_values": { "type": "object", "description": "Map of field names to values after the update." } }, "required": [ "contact", "updated_fields", "previous_values", "current_values" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeContactUpdated" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "automation.triggered": { "post": { "operationId": "webhook.automation_triggered", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nAn automation rule was executed.", "summary": "Automation triggered", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "automation.triggered" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "automation.triggered", "data": { "automation": { "id": "c3d327ab-3ef6-4d19-8ee1-11b06c912cd6", "name": "Assign Sales Agent", "trigger_type": "message_received" }, "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702", "name": "John Doe", "email": "john@example.com", "phone": null } }, "occurred_at": "2026-02-04T10:30:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `automation.triggered`." }, "data": { "type": "object", "description": "Payload for automation.triggered.", "examples": [ { "automation": { "id": "c3d327ab-3ef6-4d19-8ee1-11b06c912cd6", "name": "Assign Sales Agent", "trigger_type": "message_received" }, "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702", "name": "John Doe", "email": "john@example.com", "phone": null } } ], "properties": { "automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "trigger_type": { "type": "string" } }, "required": [ "id", "name", "trigger_type" ] }, "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." } }, "required": [ "id", "channel", "status" ] }, "visitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Visitor\/contact ID." }, "name": { "type": "string", "description": "Visitor name. Omitted when empty." }, "email": { "type": [ "string", "null" ], "description": "Visitor email. Always present; null when unknown." }, "phone": { "type": [ "string", "null" ], "description": "Visitor phone. Always present; null when unknown." } }, "required": [ "id", "email", "phone" ] } }, "required": [ "automation", "conversation", "visitor" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeAutomationTriggered" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "conversation.resolved": { "post": { "operationId": "webhook.conversation_resolved", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nA conversation was resolved by an agent, automation, or system.\n\n> resolved_by uses the same object shape as assigned_by on tag.assigned and agent.assigned: agent, automation, or system.", "summary": "Conversation resolved", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "conversation.resolved" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "conversation.resolved", "data": { "conversation": { "id": "conv_123", "channel": "website", "status": "resolved", "widget_name": "Main site widget", "identifier": "wdg_abc123", "resolved_at": "2026-02-04T11:00:00Z" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": null }, "agent": { "id": "agent_789", "name": "Sarah", "email": "sarah@example.com" }, "resolved_by": { "agent": { "id": "agent_789", "name": "Sarah", "email": "sarah@example.com" } } }, "occurred_at": "2026-02-04T11:00:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `conversation.resolved`." }, "data": { "type": "object", "description": "Payload for conversation.resolved.", "examples": [ { "conversation": { "id": "conv_123", "channel": "website", "status": "resolved", "widget_name": "Main site widget", "identifier": "wdg_abc123", "resolved_at": "2026-02-04T11:00:00Z" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": null }, "agent": { "id": "agent_789", "name": "Sarah", "email": "sarah@example.com" }, "resolved_by": { "agent": { "id": "agent_789", "name": "Sarah", "email": "sarah@example.com" } } } ], "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." }, "resolved_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "channel", "status" ] }, "visitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Visitor\/contact ID." }, "name": { "type": "string", "description": "Visitor name. Omitted when empty." }, "email": { "type": [ "string", "null" ], "description": "Visitor email. Always present; null when unknown." }, "phone": { "type": [ "string", "null" ], "description": "Visitor phone. Always present; null when unknown." } }, "required": [ "id", "email", "phone" ] }, "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent ID." }, "name": { "type": "string", "description": "Agent display name." }, "email": { "type": "string", "description": "Agent email when available." } }, "required": [ "id", "name" ] }, "resolved_by": { "type": "object", "description": "Who performed the action. Contains exactly one of: agent, automation, or system.", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent ID." }, "name": { "type": "string", "description": "Agent display name." }, "email": { "type": "string", "description": "Agent email when available." } }, "required": [ "id", "name" ] }, "automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "system": { "type": "object" } } } }, "required": [ "conversation", "visitor", "agent", "resolved_by" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeConversationResolved" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "agent.assigned": { "post": { "operationId": "webhook.agent_assigned", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nAn agent was assigned to a conversation.\n\n> assigned_by uses the same object shape as tag.assigned: agent, automation (id UUID + name), or system.", "summary": "Agent assigned", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "agent.assigned" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "agent.assigned", "data": { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "agent": { "id": "agent_789", "name": "Sarah", "email": "sarah@example.com" }, "assigned_by": { "automation": { "id": "c3d327ab-3ef6-4d19-8ee1-11b06c912cd6", "name": "Assign Sales Agent" } }, "assigned_at": "2026-02-04T10:35:00Z" }, "occurred_at": "2026-02-04T10:35:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `agent.assigned`." }, "data": { "type": "object", "description": "Payload for agent.assigned.", "examples": [ { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "agent": { "id": "agent_789", "name": "Sarah", "email": "sarah@example.com" }, "assigned_by": { "automation": { "id": "c3d327ab-3ef6-4d19-8ee1-11b06c912cd6", "name": "Assign Sales Agent" } }, "assigned_at": "2026-02-04T10:35:00Z" } ], "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." } }, "required": [ "id", "channel", "status" ] }, "visitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Visitor\/contact ID." }, "name": { "type": "string", "description": "Visitor name. Omitted when empty." }, "email": { "type": [ "string", "null" ], "description": "Visitor email. Always present; null when unknown." }, "phone": { "type": [ "string", "null" ], "description": "Visitor phone. Always present; null when unknown." } }, "required": [ "id", "email", "phone" ] }, "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent ID." }, "name": { "type": "string", "description": "Agent display name." }, "email": { "type": "string", "description": "Agent email when available." } }, "required": [ "id", "name" ] }, "assigned_by": { "type": "object", "description": "Who performed the action. Contains exactly one of: agent, automation, or system.", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent ID." }, "name": { "type": "string", "description": "Agent display name." }, "email": { "type": "string", "description": "Agent email when available." } }, "required": [ "id", "name" ] }, "automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "system": { "type": "object" } } }, "assigned_at": { "type": "string", "format": "date-time" } }, "required": [ "conversation", "visitor", "agent", "assigned_by", "assigned_at" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeAgentAssigned" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "contact.form.submitted": { "post": { "operationId": "webhook.contact_form_submitted", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nA visitor submitted a contact or offline form.\n\n> data.visitor includes id, name, email, and phone (null when unknown).", "summary": "Contact form submitted", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "contact.form.submitted" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "contact.form.submitted", "data": { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "fields": { "message": "Please contact me", "company": "Acme Inc" } }, "occurred_at": "2026-02-04T10:30:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `contact.form.submitted`." }, "data": { "type": "object", "description": "Payload for contact.form.submitted.", "examples": [ { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "fields": { "message": "Please contact me", "company": "Acme Inc" } } ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeContactFormSubmitted" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "tag.assigned": { "post": { "operationId": "webhook.tag_assigned", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nA tag was added to a conversation or contact.", "summary": "Tag assigned", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "tag.assigned" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "tag.assigned", "data": { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "tag": { "name": "vip" }, "assigned_by": { "agent": { "id": "0fbcf0f5-973a-4d6a-a1be-d777b6b2f69a", "name": "Sarah", "email": "sarah@example.com" } } }, "occurred_at": "2026-02-04T10:30:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `tag.assigned`." }, "data": { "type": "object", "description": "Payload for tag.assigned.", "examples": [ { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "tag": { "name": "vip" }, "assigned_by": { "agent": { "id": "0fbcf0f5-973a-4d6a-a1be-d777b6b2f69a", "name": "Sarah", "email": "sarah@example.com" } } } ], "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." } }, "required": [ "id", "channel", "status" ] }, "visitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Visitor\/contact ID." }, "name": { "type": "string", "description": "Visitor name. Omitted when empty." }, "email": { "type": [ "string", "null" ], "description": "Visitor email. Always present; null when unknown." }, "phone": { "type": [ "string", "null" ], "description": "Visitor phone. Always present; null when unknown." } }, "required": [ "id", "email", "phone" ] }, "tag": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "assigned_by": { "type": "object", "description": "Who performed the action. Contains exactly one of: agent, automation, or system.", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent ID." }, "name": { "type": "string", "description": "Agent display name." }, "email": { "type": "string", "description": "Agent email when available." } }, "required": [ "id", "name" ] }, "automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "system": { "type": "object" } } } }, "required": [ "conversation", "visitor", "tag", "assigned_by" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeTagAssigned" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "tag.removed": { "post": { "operationId": "webhook.tag_removed", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nA tag was removed from a conversation or contact.", "summary": "Tag removed", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "tag.removed" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "tag.removed", "data": { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "tag": { "name": "vip" }, "removed_by": { "agent": { "id": "0fbcf0f5-973a-4d6a-a1be-d777b6b2f69a", "name": "Sarah", "email": "sarah@example.com" } } }, "occurred_at": "2026-02-04T10:30:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `tag.removed`." }, "data": { "type": "object", "description": "Payload for tag.removed.", "examples": [ { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "tag": { "name": "vip" }, "removed_by": { "agent": { "id": "0fbcf0f5-973a-4d6a-a1be-d777b6b2f69a", "name": "Sarah", "email": "sarah@example.com" } } } ], "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." } }, "required": [ "id", "channel", "status" ] }, "visitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Visitor\/contact ID." }, "name": { "type": "string", "description": "Visitor name. Omitted when empty." }, "email": { "type": [ "string", "null" ], "description": "Visitor email. Always present; null when unknown." }, "phone": { "type": [ "string", "null" ], "description": "Visitor phone. Always present; null when unknown." } }, "required": [ "id", "email", "phone" ] }, "tag": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "removed_by": { "type": "object", "description": "Who performed the action. Contains exactly one of: agent, automation, or system.", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent ID." }, "name": { "type": "string", "description": "Agent display name." }, "email": { "type": "string", "description": "Agent email when available." } }, "required": [ "id", "name" ] }, "automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "system": { "type": "object" } } } }, "required": [ "conversation", "visitor", "tag", "removed_by" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeTagRemoved" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "custom.data.assigned": { "post": { "operationId": "webhook.custom_data_assigned", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nCustom data was added to a conversation or contact.", "summary": "Custom data assigned", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "custom.data.assigned" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "custom.data.assigned", "data": { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "custom_data": { "plan": "enterprise" }, "assigned_by": { "automation": { "id": "c3d327ab-3ef6-4d19-8ee1-11b06c912cd6", "name": "Assign Sales Agent" } } }, "occurred_at": "2026-02-04T10:30:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `custom.data.assigned`." }, "data": { "type": "object", "description": "Payload for custom.data.assigned.", "examples": [ { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "custom_data": { "plan": "enterprise" }, "assigned_by": { "automation": { "id": "c3d327ab-3ef6-4d19-8ee1-11b06c912cd6", "name": "Assign Sales Agent" } } } ], "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." } }, "required": [ "id", "channel", "status" ] }, "visitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Visitor\/contact ID." }, "name": { "type": "string", "description": "Visitor name. Omitted when empty." }, "email": { "type": [ "string", "null" ], "description": "Visitor email. Always present; null when unknown." }, "phone": { "type": [ "string", "null" ], "description": "Visitor phone. Always present; null when unknown." } }, "required": [ "id", "email", "phone" ] }, "custom_data": { "type": "object", "description": "Single key\/value pair for the assigned custom data field." }, "assigned_by": { "type": "object", "description": "Who performed the action. Contains exactly one of: agent, automation, or system.", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent ID." }, "name": { "type": "string", "description": "Agent display name." }, "email": { "type": "string", "description": "Agent email when available." } }, "required": [ "id", "name" ] }, "automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "system": { "type": "object" } } } }, "required": [ "conversation", "visitor", "custom_data", "assigned_by" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeCustomDataAssigned" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } }, "custom.data.removed": { "post": { "operationId": "webhook.custom_data_removed", "description": "Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.\n\nCustom data was removed from a conversation or contact.", "summary": "Custom data removed", "parameters": [ { "name": "X-Chatway-Event", "in": "header", "required": true, "description": "Event name for this delivery.", "schema": { "type": "string" }, "example": "custom.data.removed" }, { "name": "X-Chatway-Webhook-Id", "in": "header", "required": true, "description": "Unique webhook subscription ID.", "schema": { "type": "string", "format": "uuid" }, "example": "9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b" }, { "name": "X-Chatway-Delivery-Id", "in": "header", "required": true, "description": "Unique ID for this HTTP delivery attempt (`del_\u2026`).", "schema": { "type": "string" }, "example": "del_456" }, { "name": "X-Chatway-Delivery-Attempt", "in": "header", "required": true, "description": "Attempt number for this event (`1` on first try). Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1" }, { "name": "X-Chatway-Timestamp", "in": "header", "required": true, "description": "Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header.", "schema": { "type": "string" }, "example": "1785933000" }, { "name": "X-Chatway-Signature", "in": "header", "required": true, "description": "HMAC SHA256 signature prefixed with `sha256=`.", "schema": { "type": "string" }, "example": "sha256=3c9f5e2b1a0d4c8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4" } ], "requestBody": { "description": "Signed JSON envelope for this event.", "required": true, "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "evt_1234567890abcdef1234567890abcdef", "event": "custom.data.removed", "data": { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "custom_data": { "plan": "enterprise" }, "removed_by": { "automation": { "id": "c3d327ab-3ef6-4d19-8ee1-11b06c912cd6", "name": "Assign Sales Agent" } } }, "occurred_at": "2026-02-04T10:30:00Z", "version": "2026-09" } ], "properties": { "id": { "type": "string", "description": "Stable event ID (`evt_\u2026`). Same across HTTP retries for this notification." }, "event": { "type": "string", "description": "Event name. For this webhook, always `custom.data.removed`." }, "data": { "type": "object", "description": "Payload for custom.data.removed.", "examples": [ { "conversation": { "id": "conv_123", "channel": "website", "status": "open", "widget_name": "Main site widget", "identifier": "wdg_abc123" }, "visitor": { "id": "vis_456", "name": "John Doe", "email": "john@example.com", "phone": "+1XXXXXXXXXX" }, "custom_data": { "plan": "enterprise" }, "removed_by": { "automation": { "id": "c3d327ab-3ef6-4d19-8ee1-11b06c912cd6", "name": "Assign Sales Agent" } } } ], "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Conversation ID." }, "channel": { "type": "string", "description": "Normalized channel." }, "status": { "type": "string", "description": "Conversation status." }, "widget_name": { "type": "string", "description": "Present when the conversation is tied to a website widget." }, "identifier": { "type": "string", "description": "Widget identifier when widget_name is present." } }, "required": [ "id", "channel", "status" ] }, "visitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Visitor\/contact ID." }, "name": { "type": "string", "description": "Visitor name. Omitted when empty." }, "email": { "type": [ "string", "null" ], "description": "Visitor email. Always present; null when unknown." }, "phone": { "type": [ "string", "null" ], "description": "Visitor phone. Always present; null when unknown." } }, "required": [ "id", "email", "phone" ] }, "custom_data": { "type": "object", "description": "Single key\/value pair for the removed custom data field." }, "removed_by": { "type": "object", "description": "Who performed the action. Contains exactly one of: agent, automation, or system.", "properties": { "agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Agent ID." }, "name": { "type": "string", "description": "Agent display name." }, "email": { "type": "string", "description": "Agent email when available." } }, "required": [ "id", "name" ] }, "automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "system": { "type": "object" } } } }, "required": [ "conversation", "visitor", "custom_data", "removed_by" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the business event occurred." }, "version": { "type": "string", "description": "Payload schema version." } }, "required": [ "id", "event", "data", "occurred_at", "version" ], "title": "WebhookEnvelopeCustomDataRemoved" } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge receipt." }, "410": { "description": "Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. This delivery is not retried (same as other `4xx` responses). Disable the subscription in Chatway Settings if you want deliveries to stop." } }, "security": [], "x-codeSamples": [] } } } }