{ "openapi": "3.1.0", "info": { "title": "Ha Tang API", "version": "1.0.0", "license": { "name": "MIT", "identifier": "MIT" }, "description": "The Ha Tang REST API: email, support (chat) and payments. Authenticate with `Authorization: Bearer ht_...`. Every error uses the `{statusCode, name, message}` envelope. Send `Idempotency-Key` on `POST /emails` to make retries safe." }, "servers": [ { "url": "https://api.hatang.dev" } ], "security": [ { "bearerAuth": [] } ], "x-tagGroups": [ { "name": "Email", "tags": [ "Emails", "Receiving", "Domains", "Templates", "Audiences", "Contacts", "Contact properties", "Segments", "Topics", "Broadcasts", "Events", "Automations", "Metrics", "Logs", "Usage" ] }, { "name": "Support", "tags": [ "Chat sites", "Conversations", "Customers", "Visitors", "Products", "Orders", "Tickets", "Flows", "Workflows", "Campaigns", "Routing rules", "Canned responses", "ZNS", "Reports and ratings", "Knowledge" ] }, { "name": "Payments guide", "tags": [ "Payments guide: Overview", "Payments guide: Before you start", "Payments guide: Choose an integration", "Payments guide: Use the Node SDK", "Payments guide: Receive transfers only (no order)", "Payments guide: Create a payment", "Payments guide: Payment with e-invoice", "Payments guide: How the payer pays", "Payments guide: Receiving results", "Payments guide: Verify IPN signatures (HMAC)", "Payments guide: Verify webhooks (Svix)", "Payments guide: Testing in development" ] }, { "name": "Payments", "tags": [ "Payments", "Transactions", "Bank connections", "E-invoices", "Checkout", "Integrations" ] }, { "name": "Platform", "tags": [ "API Keys", "Webhooks", "Tracking" ] }, { "name": "Webhook events", "tags": [ "Email events", "Support events", "Payments events" ] } ], "tags": [ { "name": "Payments guide: Overview", "x-displayName": "Overview", "description": "Take VietQR bank transfers straight into **your own bank account**, get told the moment money arrives, and (optionally) issue the e-invoice (hóa đơn điện tử) for the order. Ha Tang never holds the money: the payer transfers to your account, and Ha Tang reads its balance changes and matches them to your orders.\n\nThis guide walks through the whole integration, section by section. The endpoint reference is in the Payments group below it.\n\n### How it works\n\n1. You link your bank account once (dashboard → Payments settings → Bank accounts). The bank confirms the link with a code it texts to the account holder.\n2. You either create a **payment** for each order, or just show your bank account and let Ha Tang report every transfer.\n3. The payer scans the VietQR with any Vietnamese banking app (or transfers by hand) with the **payment code** in the transfer description.\n4. The bank notifies Ha Tang within seconds. Ha Tang matches the code to your payment and notifies you: an **IPN** call to the URL you gave for that payment, and/or **webhooks** for your whole team.\n5. If you asked for one, the e-invoice is created at your e-invoice provider (Mắt Bão), then sent for approval, and its number and lookup code come back to you.\n\n```\nYour server ──POST /payments──► Ha Tang ──VietQR / checkout page─► Payer\n ▲ │ bank transfer\n │ balance change ▼\nYour server ◄──IPN / webhook──── Ha Tang ◄─────────────────────── Your bank account\n │\n └──draft → approval──► Mắt Bão (e-invoice)\n```" }, { "name": "Payments guide: Before you start", "x-displayName": "Before you start", "description": "**API key.** Create a key in the dashboard (API Keys) with the **Payments** scopes (`payments:read`, `payments:write`) and send it on every request:\n\n```http\nAuthorization: Bearer ht_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n```\n\n**Environments.** Payments has two separate environments; nothing is shared between them (bank accounts, payments, invoices, integration keys).\n\n| Environment | `development` | `production` |\n|---|---|---|\n| Bank | the development bank: pick any Vietnamese bank for the QR, transfers are simulated with an API call | your real bank account, linked with the code the bank texts the holder |\n| E-invoices | the provider's sandbox (Mắt Bão demo), nothing reaches the tax office | real invoices under your tax code |\n| Choose it with | header `Hatang-Environment: development` | no header (the default) |\n\nEvery response repeats the environment in the `Hatang-Environment` header, and every payments object has an `environment` field. The Node SDK takes it as an option: `new Hatang(key, { environment: \"development\" })`.\n\n**Base URL.** `https://api.hatang.dev`. All amounts are integers in VND.\n\n**Errors.** Every error has the same shape; branch on `name`, not on the message:\n\n```json\n{ \"statusCode\": 422, \"name\": \"validation_error\", \"message\": \"amount: Number must be greater than or equal to 1\" }\n```\n\n| `name` | HTTP | When |\n|---|---|---|\n| `validation_error` | 422 | A field is missing or wrong |\n| `invalid_idempotent_request` | 400 | The `Idempotency-Key` was already used with a different body |\n| `environment_mismatch` | 403 | E.g. a simulated transfer in production, a real bank in development |\n| `not_found` | 404 | Unknown id, or it belongs to the other environment |\n| `invalid_state` | 409 | E.g. editing an invoice that was already sent for approval |\n| `invoice_provider_error` | 422 | The e-invoice provider refused the request; the message says why |\n| `rate_limit_exceeded` | 429 | More than 20 Payments requests per second per team; retry after `Retry-After` |" }, { "name": "Payments guide: Choose an integration", "x-displayName": "Choose an integration", "description": "| Integration | Webhook only | Order (payment) | Order + e-invoice |\n|---|---|---|---|\n| You create something per order | No | `POST /payments` | `POST /payments` with `invoice` |\n| What the payer puts in the description | Your own order code (e.g. `DH1001`) | The payment code Ha Tang gives you (e.g. `HTBF7RDGVQ`) | Same |\n| Ha Tang tells you | `transaction.received` with the code it found | Payment paid / partially paid / overpaid / expired | The same, plus the invoice number |\n| Hosted checkout page, expiry | No | Yes | Yes |\n| E-invoice | Only if you create one yourself (`POST /einvoices` with `transaction_id`) | No | Created automatically when paid |\n\nYou can mix them on the same bank account: a transfer is always matched against your payments first, so a payment is never reported twice." }, { "name": "Payments guide: Use the Node SDK", "x-displayName": "Use the Node SDK", "description": "`@hatang/sdk` wraps everything in this guide: creating orders, confirming payment, and verifying IPN calls and webhooks. It runs on Node 20+, and its verification helpers use Web Crypto only, so they also run on Bun, Deno and edge runtimes (Vercel, Cloudflare Workers). Every API method returns `{ data, error }` and never throws for an API error.\n\n```bash\nnpm install @hatang/sdk\n```\n\n```ts\nimport { Hatang } from \"@hatang/sdk\";\n\nexport const hatang = new Hatang(process.env.HATANG_API_KEY!, {\n // Remove in production. Or set HATANG_ENVIRONMENT=development.\n environment: \"development\",\n});\n```\n\n**1. Create the order's payment.** `createOrder` uses your order id as the idempotency key: calling it twice for the same order (a double click, a retried request) returns the same payment. It also stores the id in `metadata.order_id`.\n\n```ts\nconst { data: payment, error } = await hatang.payments.createOrder({\n order_id: \"SO-1001\",\n amount: 150_000,\n description: \"Đơn hàng #1001\",\n return_url: \"https://shop.example.vn/orders/SO-1001\",\n ipn_url: \"https://shop.example.vn/api/hatang/ipn\",\n // Optional: issue the e-invoice once it is paid.\n invoice: {\n buyer: { name: \"Nguyễn Văn Khách\", tax_code: \"0109876543\", email: \"ketoan@khach.vn\" },\n items: [{ name: \"Gói dịch vụ\", quantity: 1, unit_price: 136_364, vat_rate: 10 }],\n },\n});\nif (error) throw new Error(`${error.name}: ${error.message}`);\n\n// Send the payer to the hosted checkout page…\nredirect(payment.checkout_url);\n// …or show the QR yourself: , bank details in payment.bank, code in payment.code.\n```\n\nAdd `code: \"SO1002\"` to use your own order number as the transfer description instead of the generated `HT…` one (see **The payment code** under *Create a payment*).\n\n**2. Receive the IPN.** Pass the raw body and the headers; `constructIpnEvent` checks the HMAC signature and returns the parsed call, or throws `HatangSignatureError`.\n\nNext.js (App Router):\n\n```ts\n// app/api/hatang/ipn/route.ts\nimport { constructIpnEvent, HatangSignatureError } from \"@hatang/sdk\";\n\nexport async function POST(req: Request) {\n const raw = await req.text(); // before any JSON parsing\n try {\n const ipn = await constructIpnEvent(raw, req.headers, process.env.HATANG_SECRET_KEY!);\n if (await alreadyHandled(ipn.id)) return new Response(null, { status: 200 });\n const order = ipn.data.metadata.order_id as string;\n if (ipn.data.status === \"paid\" || ipn.data.status === \"overpaid\") await markOrderPaid(order, ipn.data.paid_amount);\n if (ipn.data.invoice?.status === \"issued\") await saveInvoiceNumber(order, ipn.data.invoice.number);\n return new Response(null, { status: 200 });\n } catch (err) {\n if (err instanceof HatangSignatureError) return new Response(null, { status: 401 });\n throw err; // a 5xx makes Ha Tang retry later\n }\n}\n```\n\nExpress:\n\n```ts\nimport express from \"express\";\nimport { constructIpnEvent } from \"@hatang/sdk\";\n\napp.post(\"/api/hatang/ipn\", express.raw({ type: \"application/json\" }), async (req, res) => {\n const ipn = await constructIpnEvent(req.body, req.headers, process.env.HATANG_SECRET_KEY!).catch(() => null);\n if (!ipn) return res.sendStatus(401);\n await queue.add(\"hatang-ipn\", ipn); // handle it in the background, answer fast\n res.sendStatus(200);\n});\n```\n\n**3. Confirm before you fulfil.** When the payer comes back to your `return_url`, ask Ha Tang instead of trusting the browser. `verify` returns `verified: true` only if the payment is paid (or overpaid) and matches what you pass:\n\n```ts\nconst { data: check } = await hatang.payments.verify(paymentId, {\n order_id: \"SO-1001\",\n amount: 150_000,\n environment: \"production\", // a development payment never unlocks a real order\n});\nif (check?.verified) await fulfil(\"SO-1001\");\nelse console.log(check?.reasons); // e.g. [\"status is partially_paid\"], [\"belongs to another order\"]\n```\n\n**4. Webhooks (optional)** for everything in your team, not just one payment:\n\n```ts\nimport { constructWebhookEvent, type Payment } from \"@hatang/sdk\";\n\nconst event = await constructWebhookEvent(raw, req.headers, process.env.HATANG_WEBHOOK_SECRET!); // whsec_…\nif (event.type === \"payment.succeeded\") await markOrderPaid(event.data.metadata.order_id as string, event.data.paid_amount);\n```\n\n**5. Test in development.** With `environment: \"development\"` and the simulated bank linked:\n\n```ts\nawait hatang.payments.simulateTransfer({ payment_id: payment.id }); // pays it in full\nawait hatang.payments.simulateTransfer({ payment_id: payment.id, amount: 50_000 }); // a partial transfer\n```\n\nThe transfer goes through the same processing as a real bank's, so your IPN handler and webhooks receive the same calls they will in production.\n\n| SDK | Does |\n|---|---|\n| `payments.createOrder({ order_id, amount, … })` | Create the payment for an order; safe to retry |\n| `payments.create(payload, { idempotencyKey })` | The same with your own key and metadata |\n| `payments.verify(id, { order_id, amount, environment })` | `{ verified, paid, reasons, payment }` |\n| `payments.get` / `list` / `cancel` / `markPaid` | Read and manage payments |\n| `payments.ipnDeliveries(id)` | The IPN calls made for a payment |\n| `payments.qr({ amount, content })` | A VietQR for the webhook-only flow |\n| `payments.simulateTransfer(…)` | Development only |\n| `einvoices.create` / `get` / `retry` / `history` | E-invoices outside a payment |\n| `constructIpnEvent(raw, headers, secretKey)` / `verifyIpn(raw, signature, secretKey)` | IPN signature (HMAC-SHA256) |\n| `constructWebhookEvent(raw, headers, secret)` / `verifyWebhook(…)` | Webhook signature (Svix), with a 5-minute timestamp window |" }, { "name": "Payments guide: Receive transfers only (no order)", "x-displayName": "Receive transfers only (no order)", "description": "Use this when your system already has order numbers and you only want to know when money for them arrives (like a static QR at a shop counter).\n\n**1. Tell Ha Tang what your order codes look like.** Set `payment_code_pattern` on the bank account: a prefix plus a length range. Ha Tang then looks for it in every transfer description.\n\n```http\nPATCH /payments/bank-connections/bcn_01a0b90428fd7c499145a12c133abe41\nContent-Type: application/json\n\n{ \"config\": { \"payment_code_pattern\": { \"prefix\": \"DH\", \"min_length\": 4, \"max_length\": 8, \"charset\": \"digits\" } } }\n```\n\n**2. Show a VietQR with your code.** `GET /payments/qr` builds one for any amount and content; nothing is stored. Use `format=svg` for an image, or render `payload` with any QR library.\n\n```http\nGET /payments/qr?amount=99000&content=DH20250919\n```\n\n```json\n{\n \"object\": \"vietqr\",\n \"payload\": \"00020101021238530010A0000007270123000697042201099104526580208QRIBFTTA53037045405990005802VN62140810DH202509196304FCC9\",\n \"connection_id\": \"bcn_01a0b90428fd7c499145a12c133abe41\",\n \"bank\": { \"bin\": \"970422\", \"account_number\": \"910452658\", \"account_name\": \"NGUYEN VAN A\" },\n \"amount\": 99000,\n \"content\": \"DH20250919\"\n}\n```\n\nLeave out `amount` for a QR where the payer types the amount (a counter sticker).\n\n**3. Receive `transaction.received`.** Subscribe a webhook endpoint to it (see Receiving results and Verify webhooks). `merchant_code` is your code as found in the description, after removing accents, spaces and punctuation and uppercasing (`dh 2025-0919` → `DH20250919`); `null` if none was found.\n\n```json\n{\n \"type\": \"transaction.received\",\n \"created_at\": \"2026-09-19T09:34:12.946Z\",\n \"data\": {\n \"object\": \"transaction\",\n \"id\": \"txn_01a0b90429dc79c7a5689c7a0c485a01\",\n \"environment\": \"production\",\n \"connection_id\": \"bcn_01a0b90428fd7c499145a12c133abe41\",\n \"direction\": \"in\",\n \"amount\": 99000,\n \"currency\": \"VND\",\n \"description\": \"DH20250919 chuyen tien\",\n \"merchant_code\": \"DH20250919\",\n \"reference\": \"FT1789810452930810\",\n \"counterparty\": { \"account\": \"0987654321\", \"name\": \"NGUYEN VAN KHACH\", \"bank\": \"970436\" },\n \"booked_at\": \"2026-09-19T09:34:12.930Z\",\n \"source\": \"push\",\n \"payment_id\": null,\n \"match_status\": \"unmatched\",\n \"created_at\": \"2026-09-19T09:34:12.946Z\"\n }\n}\n```\n\nFind the order by `merchant_code`, compare `amount` with what it should be, and store `data.id`: the same transaction is never reported twice, but your endpoint may receive the same delivery again after a timeout.\n\nWhich transfers are reported is set per bank account (`transaction_events` in the account config, or the dashboard): money in only (default) or also money out, only transfers where a code was found, and a minimum amount." }, { "name": "Payments guide: Create a payment", "x-displayName": "Create a payment", "description": "**1. Create it** when the customer checks out. Send an `Idempotency-Key` (your order id works well) so a retried request returns the same payment instead of a second one.\n\n```http\nPOST /payments\nIdempotency-Key: order-1001\nContent-Type: application/json\n\n{\n \"amount\": 150000,\n \"description\": \"Đơn hàng #1001\",\n \"expires_in\": 3600,\n \"return_url\": \"https://shop.example.vn/orders/1001\",\n \"ipn_url\": \"https://shop.example.vn/hatang/ipn\",\n \"customer\": { \"name\": \"Trần Thị B\", \"email\": \"b@example.vn\" },\n \"metadata\": { \"order_id\": \"1001\" }\n}\n```\n\n| Field | Meaning |\n|---|---|\n| `amount` | Required. VND, VAT included: what the payer transfers |\n| `description` | Shown to the payer on the checkout page |\n| `expires_in` | Seconds until the payment expires (default 86400, max 30 days) |\n| `connection_id` | Which bank account receives the money; required only when you have several |\n| `return_url` | Where the checkout page sends the payer after paying |\n| `ipn_url` | Your endpoint for this payment's IPN calls (see Receiving results) |\n| `customer`, `metadata` | Yours; returned as given. `metadata` values: string, number, boolean or null |\n| `invoice` | Issue an e-invoice when paid (see Payment with e-invoice) |\n\n```json\n{\n \"object\": \"payment\",\n \"id\": \"pay_01a0b904297873e8b3524a26fdca0ab5\",\n \"environment\": \"production\",\n \"status\": \"pending\",\n \"amount\": 150000,\n \"paid_amount\": 0,\n \"currency\": \"VND\",\n \"code\": \"HTBF7RDGVQ\",\n \"description\": \"Đơn hàng #1001\",\n \"connection_id\": \"bcn_01a0b90428fd7c499145a12c133abe41\",\n \"bank\": { \"bin\": \"970422\", \"name\": \"MB Bank\", \"account_number\": \"910452658\", \"account_name\": \"NGUYEN VAN A\" },\n \"qr\": {\n \"payload\": \"00020101021238530010A0000007270123000697042201099104526580208QRIBFTTA530370454061500005802VN62140810HTBF7RDGVQ63044DEC\",\n \"image_url\": \"https://api.hatang.dev/pay/pay_01a0b904297873e8b3524a26fdca0ab5/qr.svg\"\n },\n \"checkout_url\": \"https://app.hatang.dev/pay/pay_01a0b904297873e8b3524a26fdca0ab5\",\n \"return_url\": \"https://shop.example.vn/orders/1001\",\n \"ipn_url\": \"https://shop.example.vn/hatang/ipn\",\n \"customer\": { \"name\": \"Trần Thị B\", \"email\": \"b@example.vn\" },\n \"metadata\": { \"order_id\": \"1001\" },\n \"invoice\": null,\n \"expires_at\": \"2026-09-19T10:34:12.856Z\",\n \"paid_at\": null,\n \"canceled_at\": null,\n \"created_at\": \"2026-09-19T09:34:12.856Z\"\n}\n```\n\n**2. Let the customer pay** (see How the payer pays): redirect to `checkout_url`, or show `qr` and the `bank` details yourself.\n\n**3. Learn the result** from the IPN call or a webhook (see Receiving results), then fulfil the order when `status` is `paid` (or `overpaid`).\n\n**Statuses.**\n\n| `status` | Meaning | Event |\n|---|---|---|\n| `pending` | Waiting for the transfer | `payment.created` |\n| `paid` | The full amount arrived (`paid_at` is set) | `payment.succeeded` |\n| `partially_paid` | Less than the amount arrived; a second transfer with the same code adds up | `payment.partially_paid` |\n| `overpaid` | More than the amount arrived | `payment.overpaid` |\n| `expired` | Nothing (or not enough) arrived before `expires_at` | `payment.expired` |\n| `canceled` | You canceled it (`POST /payments/{id}/cancel`, only while `pending`) | `payment.canceled` |\n\nMoney that arrives after `expires_at` is still recorded: the payment becomes `paid` and you are notified, so decide yourself whether to fulfil late orders. If money arrived some other way (cash, a transfer without the code), `POST /payments/{id}/mark-paid` records it by hand.\n\n**The payment code.** `code` is a prefix (`HT` by default, changeable per bank account) plus 8 characters without look-alikes (no `0/O`, `1/I`). The payer must put it in the transfer description. Anything around it is fine (`CK HTBF7RDGVQ thanh toan`), and case, spaces and accents are ignored. The VietQR already carries it, so a payer who scans does not have to type it.\n\n**Your own code.** Send `code` with the payment and that is the transfer description instead — your order number, so your statement and your orders read the same:\n\n```json\n{ \"amount\": 275000, \"code\": \"DH1002\" }\n```\n\nLetters and digits only, 6 to 20 of them, upper-cased. It must be unused on that bank account (reusing one is a `409 code_taken`), and it is matched the same way: anything around it in the description is ignored. Two rules worth knowing:\n\n- **Longer is safer.** The code is found by looking for it inside the description, so a short common one (`ORDER1`) will match a transfer that merely happens to contain it. Order numbers with your own prefix (`DH1002`) are specific enough.\n- **If one code is part of another** (`DH1002` and `DH10024`), the longer one wins the transfer that carries it." }, { "name": "Payments guide: Payment with e-invoice", "x-displayName": "Payment with e-invoice", "description": "First connect your e-invoice provider account once: dashboard → Payments settings → Invoice providers, or `POST /einvoices/connections/check` (signs in and lists your templates) then `POST /einvoices/connections` with the chosen template. The first provider becomes the default.\n\nThen add an `invoice` block to the payment. Nothing is sent to the provider until the payment is paid.\n\n```http\nPOST /payments\nContent-Type: application/json\n\n{\n \"amount\": 275000,\n \"description\": \"Đơn hàng #1002\",\n \"ipn_url\": \"https://shop.example.vn/hatang/ipn\",\n \"metadata\": { \"order_id\": \"1002\" },\n \"invoice\": {\n \"mode\": \"publish\",\n \"template\": { \"pattern\": \"1\", \"serial\": \"C26TAT\" },\n \"buyer\": {\n \"name\": \"Nguyễn Văn Khách\",\n \"legal_name\": \"Công ty TNHH Khách Hàng\",\n \"tax_code\": \"0109876543\",\n \"address\": \"1 Tràng Tiền, Hà Nội\",\n \"email\": \"ketoan@khach.vn\"\n },\n \"items\": [{ \"name\": \"Gói dịch vụ tháng 9\", \"unit\": \"gói\", \"quantity\": 1, \"unit_price\": 250000, \"vat_rate\": 10 }],\n \"payment_method\": \"CK\"\n }\n}\n```\n\n| Field | Meaning |\n|---|---|\n| `mode` | `publish`: create the draft, then send it for approval (sign) automatically. `draft`: stop at the draft; you review it and call `POST /einvoices/{id}/publish`. Default: the provider connection's setting |\n| `template` | Template (`pattern`, ký hiệu mẫu số) and series (`serial`, ký hiệu). Default: the connection's. `GET /einvoices/connections/{id}/templates` lists yours |\n| `buyer` | `name` (a person) and/or `legal_name` (a company), `tax_code`, `address`, `email`, `phone`, `buyer_code` |\n| `items` | `name`, `quantity`, `unit_price` (before VAT), `vat_rate` (`10`, `8`, `5`, `0`, `-1` not subject, `-2` not declared), optional `unit`, `code`, `discount` |\n| `payment_method`, `note` | Printed on the invoice |\n\nMake the item totals (after VAT) equal the payment `amount`: here 250,000 + 10% = 275,000.\n\n**What happens after payment.** Every invoice takes the same steps, each queued and retried on its own:\n\n| `invoice.status` on the payment | Meaning |\n|---|---|\n| `waiting_for_payment` | Not paid yet; nothing sent |\n| `creating` | Paid; the draft is being created at the provider |\n| `draft` | The draft exists (stops here in `draft` mode) |\n| `publishing` | Sent for approval (being signed) |\n| `issued` | Signed: it has a `number` and `lookup_code`; waiting for the tax office |\n| `tax_accepted` / `tax_rejected` | The tax office's answer (`tax_authority_code` when accepted) |\n| `failed` | The provider refused a step; `error` says why and `failed_step` which step |\n\nThe payment's `invoice` field always shows where it stands, and every change is sent as an IPN and as `invoice.*` webhooks:\n\n```json\n\"invoice\": {\n \"requested\": true,\n \"mode\": \"publish\",\n \"status\": \"issued\",\n \"id\": \"einv_01a0b90429f678e68ed7de882720a2b4\",\n \"number\": \"8003\",\n \"series\": \"1C26TAT\",\n \"template\": { \"pattern\": \"1\", \"serial\": \"C26TAT\" },\n \"lookup_code\": \"HTXAEM9P3AYXSM\",\n \"tax_authority_code\": null,\n \"pdf_url\": \"https://…\",\n \"sync_state\": \"in_sync\",\n \"issued_at\": \"2026-09-18T17:00:00.000Z\",\n \"error\": null,\n \"failed_step\": null\n}\n```\n\n**When a step fails.** Timeouts and provider outages are retried automatically. A refusal (for example an invalid buyer tax code) stops the invoice at `failed` with the provider's message. Fix what it says (`PATCH /einvoices/{id}` for the buyer or items when it failed while creating the draft), then `POST /einvoices/{id}/retry` runs the same step again. `GET /einvoices/{id}/history` returns every step with who made it.\n\n**Invoices without a payment.** `POST /einvoices` takes the same fields as the `invoice` block, plus `payment_id` or `transaction_id` to link it (use `transaction_id` for transfers received without an order). Invoices created or changed directly on the provider's site come back to Ha Tang too; they are marked `source: \"provider\"` in events.\n\nAn invoice sent to the tax office cannot be canceled or deleted through Ha Tang; `POST /einvoices/{id}/replace` issues a replacement. A draft can be deleted (`DELETE /einvoices/{id}`)." }, { "name": "Payments guide: How the payer pays", "x-displayName": "How the payer pays", "description": "**Scan the VietQR.** Any banking app in Vietnam scans it (NAPAS 247, instant, 24/7). The QR fills in your bank, account number, the amount and the payment code; the payer only confirms. Show it from `qr.image_url` (an SVG you can put in an ``), or render `qr.payload` with your own QR library for a custom design.\n\nThe image carries the hatang mark in the middle, and is written at error correction level H so the mark costs a scanner nothing. `qr.image_url?logo=0` gives the plain code, for printing it under branding of your own.\n\n**Use the hosted checkout page.** Redirect to `checkout_url`. It shows the QR, the bank details with copy buttons and a countdown, updates live when the money arrives (then shows the invoice number if there is one), and sends the payer to your `return_url`. It needs no login: the payment id is the only credential.\n\n**Transfer by hand.** Show `bank.name`, `bank.account_number`, `bank.account_name`, the amount and the `code`, and ask the payer to put the code in the description. This works from any bank, including internet banking on a computer.\n\n**Build your own live page.** `GET /pay/{id}/events` (server-sent events, no API key) pushes each status change to the browser, and `GET /pay/{id}` returns what the checkout page shows (only what the payer needs). Never fulfil an order from the browser's word: confirm on your server with the IPN, a webhook or `GET /payments/{id}`.\n\nIf the payer sends the wrong amount, the payment becomes `partially_paid` or `overpaid` (see Create a payment). If they forget the code, the transfer still arrives as a `transaction.received` with `payment_id: null`, and you can `mark-paid` the payment." }, { "name": "Payments guide: Receiving results", "x-displayName": "Receiving results", "description": "| Channel | IPN | Webhooks | Polling |\n|---|---|---|---|\n| For | One payment (`ipn_url` given when creating it) | Everything in your team, both environments | Any time |\n| Sent on | Every `payment.*` change except `created`, and every `invoice.*` change of that payment | The event types the endpoint subscribes to | – |\n| Body | `{ id, event_id, type, environment, created_at, data: }` | `{ type, created_at, data }` | The object |\n| Signature | `Hatang-Signature`: HMAC-SHA256 of the body with your **secret key** | Svix: `svix-id`, `svix-timestamp`, `svix-signature` | Your API key |\n| Retries | 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h (8 tries) | 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h | – |\n| Timeout | 10 s | 15 s | – |\n| Deliveries log | `GET /payments/{id}/ipn-deliveries` | `GET /webhooks/{id}/deliveries` | – |\n\nIPN and webhook URLs must be **https** and on the public internet: addresses such as `localhost`, `10.x`, `192.168.x` or `169.254.169.254` are refused. A call counts as delivered when your endpoint answers **2xx**; redirects are not followed. Answer quickly and do the work afterwards (a queue), because slow answers are retried.\n\nYour handler should:\n\n1. **Verify the signature on the raw body** (see Verify IPN signatures and Verify webhooks), before parsing the JSON.\n2. **Dedupe**: IPN `id` (or `event_id`) and webhook `svix-id` are the same on every retry of the same call.\n3. **Trust the status, not the order of arrival**: calls can arrive out of order or twice. Read `data.status` (or fetch `GET /payments/{id}`) and move your order forward only.\n4. **Check the amount and environment**: `data.paid_amount` against your order, and `environment` (a development payment must never fulfil a real order).\n\nAn IPN call as your endpoint receives it:\n\n```http\nPOST /hatang/ipn HTTP/1.1\nContent-Type: application/json\nUser-Agent: Hatang-IPN/1.0\nHatang-Access-Key: ak_Example0AccessKey0000000\nHatang-Signature: 8f0c3b1e5d7a9c2f4e6b8a0d1c3e5f7a9b2d4f6e8a0c2e4f6b8d0a2c4e6f8b0d\nHatang-Signature-Algorithm: HMAC-SHA256\nHatang-Event: payment.succeeded\nHatang-Delivery-Id: ipn_01a0b90429d87cf89e37fc2f66040ec5\nHatang-Environment: production\n\n{\"id\":\"ipn_01a0b90429d87cf89e37fc2f66040ec5\",\"event_id\":\"de_01a0b90429b57b41a2ef3510d6bf8036\",\"type\":\"payment.succeeded\",\"environment\":\"production\",\"created_at\":\"2026-09-19T09:34:12.952Z\",\"data\":{\"object\":\"payment\",\"id\":\"pay_01a0b904297873e8b3524a26fdca0ab5\",\"status\":\"paid\",\"amount\":150000,\"paid_amount\":150000,\"code\":\"HTBF7RDGVQ\",\"metadata\":{\"order_id\":\"1001\"},\"invoice\":null, …}}\n```" }, { "name": "Payments guide: Verify IPN signatures (HMAC)", "x-displayName": "Verify IPN signatures (HMAC)", "description": "Each team has an **access key** and a **secret key** per environment, created with the team: dashboard → Payments settings → Integration keys. Development keys start with `ak_test_` / `sk_test_`.\n\n- `Hatang-Access-Key` tells you which account and environment the call is for.\n- `Hatang-Signature` is the **lowercase hex HMAC-SHA256 of the raw request body**, keyed with the secret key (its UTF-8 bytes, as shown).\n\nTo verify: compute the same HMAC over the bytes you received and compare in constant time. Keep the secret key on your server only.\n\n**Node.js (Express)**\n\n```js\nimport express from \"express\";\nimport { createHmac, timingSafeEqual } from \"node:crypto\";\n\nconst SECRET = process.env.HATANG_SECRET_KEY; // sk_…\n\nfunction verifyIpn(rawBody, signature, secret) {\n const expected = createHmac(\"sha256\", secret).update(rawBody).digest(\"hex\");\n const got = String(signature ?? \"\").trim().toLowerCase();\n return got.length === expected.length && timingSafeEqual(Buffer.from(got), Buffer.from(expected));\n}\n\nconst app = express();\n// The raw bytes, not parsed JSON: re-serialising changes the body and breaks the signature.\napp.post(\"/hatang/ipn\", express.raw({ type: \"application/json\" }), async (req, res) => {\n if (!verifyIpn(req.body, req.get(\"Hatang-Signature\"), SECRET)) return res.status(401).end();\n const ipn = JSON.parse(req.body.toString(\"utf8\"));\n if (await alreadyHandled(ipn.id)) return res.status(200).end();\n await queue.add(\"hatang-ipn\", ipn); // update the order in the background\n res.status(200).end();\n});\n```\n\nWith the SDK: `constructIpnEvent(rawBody, headers, secretKey)` verifies and returns the parsed call (throws `HatangSignatureError`), or `verifyIpn(rawBody, signature, secretKey)` returns a boolean. See Use the Node SDK.\n\n**PHP**\n\n```php\n\n{\n using var ms = new MemoryStream();\n await req.Body.CopyToAsync(ms);\n var raw = ms.ToArray();\n var secret = Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable(\"HATANG_SECRET_KEY\")!);\n var expected = Convert.ToHexString(HMACSHA256.HashData(secret, raw)).ToLowerInvariant();\n var got = req.Headers[\"Hatang-Signature\"].ToString().Trim().ToLowerInvariant();\n if (!CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(got)))\n return Results.Unauthorized();\n // dedupe on the \"id\" field, then update the order\n return Results.Ok();\n});\n```\n\n**Test vector.** With secret key `sk_test_example` and body `{\"id\":\"ipn_test\",\"type\":\"payment.succeeded\"}` (exactly those bytes), the signature is `35c86d268e66be5f34c25d834de9da3ba1f0c6d26fb735266440886df6b5d955`.\n\n**Common mistakes**\n\n- Parsing the JSON and serialising it again before verifying: spacing and key order change, so the HMAC does not match. Verify the raw bytes.\n- Using the other environment's secret key: development and production have different keys; `Hatang-Environment` / the `sk_test_` prefix tell you which.\n- Comparing with `==`: use a constant-time comparison.\n- After **Create a new secret key** in the dashboard, calls are signed with the new key immediately. Retries of older calls are signed with the key current at the time they are sent, so switch the key on your server right after rotating." }, { "name": "Payments guide: Verify webhooks (Svix)", "x-displayName": "Verify webhooks (Svix)", "description": "Webhook endpoints (dashboard → Webhooks, or `POST /webhooks`) get a signing secret `whsec_…`. Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com/) / Svix format, so the `svix` or `standardwebhooks` libraries verify them:\n\n```js\nimport { Webhook } from \"svix\";\n\nconst wh = new Webhook(process.env.HATANG_WEBHOOK_SECRET); // whsec_…\n// rawBody: the request body as a string, exactly as received.\n// Throws if the signature or the timestamp (±5 min) is wrong.\nwh.verify(rawBody, {\n \"svix-id\": req.get(\"svix-id\"),\n \"svix-timestamp\": req.get(\"svix-timestamp\"),\n \"svix-signature\": req.get(\"svix-signature\"),\n});\nconst event = JSON.parse(rawBody); // { type, created_at, data }\n```\n\nWith the Ha Tang SDK, no extra dependency: `await constructWebhookEvent(rawBody, headers, secret)`.\n\nBy hand: base64-decode the secret after `whsec_`, compute HMAC-SHA256 of `{svix-id}.{svix-timestamp}.{raw body}`, base64-encode it, and compare it with each `v1,` in `svix-signature` (space-separated). Reject timestamps more than 5 minutes away from now.\n\nPayments events: `payment.created`, `payment.succeeded`, `payment.partially_paid`, `payment.overpaid`, `payment.expired`, `payment.canceled`, `transaction.received`, `bank_connection.activated`, `bank_connection.revoked`, `bank_connection.needs_reauth`, `invoice.draft_created`, `invoice.draft_updated`, `invoice.draft_deleted`, `invoice.issued`, `invoice.tax_accepted`, `invoice.tax_rejected`, `invoice.canceled`, `invoice.replaced`, `invoice.adjusted`, `invoice.failed`, `invoice.conflict`. `payment.succeeded`, `partially_paid` and `overpaid` include the matched `transaction`." }, { "name": "Payments guide: Testing in development", "x-displayName": "Testing in development", "description": "Send `Hatang-Environment: development` on every request (or use the SDK option). Then:\n\n1. Link the development bank: `POST /payments/bank-connections` `{ \"provider\": \"simulator\" }`, then confirm with the code `000000`. Or dashboard → Payments settings → Bank accounts → Add bank account.\n\n `bank_code` says which bank the QR names, so a payment's QR is a real VietQR for it: `{ \"provider\": \"simulator\", \"bank_code\": \"BIDV\", \"account_number\": \"96247001234\", \"account_name\": \"NGUYEN VAN A\" }`. Codes are the usual short ones — `MB`, `BIDV`, `ACB`, `VCB`, `ICB`, `TCB`, `VPB`, `TPB`, `STB`… — and `MB` is the default. Give your own account number and a payer's banking app really does transfer to you; no bank is integrated here, so Ha Tang does not see the money arrive and the payment only moves when you simulate the transfer or mark it paid. Leave `account_number` out and a `SIM…` number is made up instead, which no bank resolves.\n2. Create payments as in production. Their QR and checkout page work the same.\n3. Pretend the payer transferred: `POST /payments/simulate/transfer` `{ \"payment_id\": \"pay_…\" }` (the checkout page and the dashboard have a button for it too). Add `amount` for a partial or overpayment, `content` for a custom description, or `connection_id` plus `content` for a transfer without an order. The transfer goes through exactly the same processing as a real bank's, so your IPN and webhooks fire.\n4. For e-invoices, connect Mắt Bão's demo sandbox account; invoices are real sandbox invoices but never reach the tax office.\n\n**Going live checklist**\n\n- Link your real bank account in production (the bank texts the holder a code).\n- Connect your e-invoice provider in production and pick the template.\n- Configure the **production** secret key and webhook secret on your server.\n- Remove the `Hatang-Environment: development` header (or the SDK option).\n- Make sure your handler checks `environment`, the amount and duplicates." }, { "name": "Payments", "description": "Bank-transfer payments via VietQR, matched automatically. Development and production are separate: send `Hatang-Environment: development` (or use a `ht_test_` key) for the simulated bank and the invoice provider's sandbox; production is the default." }, { "name": "Transactions", "description": "Every balance change of a linked bank account." }, { "name": "Bank connections", "description": "Link the bank account that receives the money. Real banks confirm with a code texted to the account holder." }, { "name": "E-invoices", "description": "E-invoices (hóa đơn điện tử) issued under your tax code through your own provider account (Mắt Bão). Drafts or direct issue; changes made on the provider's site sync back." }, { "name": "Checkout", "description": "Public endpoints behind the hosted checkout page; the payment id is the only credential." }, { "name": "Integrations", "description": "Endpoints third parties (banks, e-invoice providers) call. Not for API clients." }, { "name": "Emails", "description": "Send transactional email and inspect delivery status and events." }, { "name": "Domains", "description": "Sending domains and the DNS records that verify them." }, { "name": "API Keys", "description": "Bearer tokens for the API and passwords for the SMTP relay." }, { "name": "Webhooks", "description": "Endpoints that receive signed, Svix-compatible event callbacks for every product." }, { "name": "Audiences", "description": "Contact lists used by broadcasts." }, { "name": "Contacts", "description": "Members of an audience." }, { "name": "Broadcasts", "description": "Marketing emails sent to a whole audience." }, { "name": "Receiving", "description": "Email that arrives at your domains with receiving on: bodies, headers and attachments." }, { "name": "Templates", "description": "Reusable email templates with variables; drafts are published before sends use them." }, { "name": "Contact properties", "description": "Custom fields on contacts, usable as merge tags." }, { "name": "Segments", "description": "Groups of contacts that broadcasts target." }, { "name": "Topics", "description": "Subscription topics contacts can opt in to or out of." }, { "name": "Events", "description": "Custom events you send for contacts; they trigger and resume automations." }, { "name": "Automations", "description": "Multi-step email journeys triggered by events." }, { "name": "Metrics", "description": "Delivery and engagement counts and rates over time." }, { "name": "Logs", "description": "Your API requests, with bodies (secrets redacted)." }, { "name": "Usage", "description": "What the business used against its plan's limits." }, { "name": "Chat sites", "description": "Websites (widget sites) of the business and their settings." }, { "name": "Conversations", "description": "Conversations on every channel, their timeline and replies." }, { "name": "Customers", "description": "One person across channels, with custom fields." }, { "name": "Visitors", "description": "Website visitors, including who is on the site right now." }, { "name": "Products", "description": "The product catalogue used in conversations and orders." }, { "name": "Orders", "description": "Orders created from conversations, with payment links." }, { "name": "Tickets", "description": "Support tickets and their SLA policies." }, { "name": "Flows", "description": "Chat flows: scripted conversations and lead capture." }, { "name": "Workflows", "description": "Automations that react to conversation events." }, { "name": "Campaigns", "description": "Proactive messages and forms shown to website visitors." }, { "name": "Routing rules", "description": "Who gets which new conversation." }, { "name": "Canned responses", "description": "Saved replies agents insert with a shortcut." }, { "name": "ZNS", "description": "Zalo Notification Service template messages to phone numbers." }, { "name": "Reports and ratings", "description": "Support reports and customer satisfaction ratings." }, { "name": "Knowledge", "description": "Documents the AI assistant answers from, pushed from your own help center, CMS or product docs under your own ids. Writes return at once and indexing runs in the background; an unchanged document is not re-indexed, and a collection sync deletes what you no longer send." }, { "name": "Email events", "description": "Webhook events for email delivery, contacts and domains." }, { "name": "Support events", "description": "Webhook events for conversations, messages, orders, tickets and ZNS." }, { "name": "Payments events", "description": "Webhook events for payments, bank transactions, bank links and e-invoices." }, { "name": "Tracking", "description": "Public endpoints embedded in emails; no authentication." } ], "paths": { "/emails": { "post": { "tags": [ "Emails" ], "summary": "Send an email", "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" } } } }, "operationId": "postEmails", "description": "Sends one email. The `from` address must be on a domain you have verified (a `403` names the domain otherwise). Up to 50 recipients across `to`, `cc` and `bcc`; up to 50 attachments as base64 `content` (attachments by `path` URL are not supported yet), with the whole message under 40 MB. Pass `scheduled_at` to send later (cancel or reschedule until then), `template` to render a published template with `variables`, and `tags` to filter events and metrics.\n\nSend an `Idempotency-Key` header to make retries safe: the same key with the same body returns the first result, the same key with a different body fails with `invalid_idempotent_request`." }, "get": { "tags": [ "Emails" ], "summary": "List emails", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Return emails older than this id" }, { "name": "before", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated statuses" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Search recipient, subject, sender or id" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "api", "smtp", "broadcast" ] } } ], "operationId": "getEmails" } }, "/emails/batch": { "post": { "tags": [ "Emails" ], "summary": "Send up to 100 emails in one call", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchSendRequest" } } } }, "operationId": "postEmailsBatch", "description": "Sends 1–100 emails in one request. Each item takes the fields of `POST /emails` except `attachments` and `scheduled_at`, which batch sends refuse. The response lists one id per email, in order." } }, "/emails/receiving": { "get": { "tags": [ "Receiving" ], "summary": "List received emails (domains with receiving on; needs email:read)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedEmailSummary" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Return emails older than this id" }, { "name": "before", "in": "query", "schema": { "type": "string" } } ], "operationId": "getEmailsReceiving", "description": "Emails received on your domains with receiving turned on, newest first. Each item is a summary; fetch one email for its body, headers and attachments." } }, "/emails/receiving/{id}": { "get": { "tags": [ "Receiving" ], "summary": "Retrieve a received email: text, HTML, headers and attachment metadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedEmail" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Received email id" } ], "operationId": "getEmailsReceivingById", "description": "A received email with its text and HTML bodies, headers and attachment metadata. Attachment download URLs come from the attachments endpoints." } }, "/emails/receiving/{id}/attachments": { "get": { "tags": [ "Receiving" ], "summary": "List a received email's attachments with download URLs (valid for an hour)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedAttachment" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Received email id" } ], "operationId": "getEmailsReceivingByIdAttachments" } }, "/emails/receiving/{id}/attachments/{attachment_id}": { "get": { "tags": [ "Receiving" ], "summary": "Retrieve one attachment with a download URL", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedAttachment" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Received email id" }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Attachment id" } ], "operationId": "getEmailsReceivingByIdAttachmentsByAttachment_id" } }, "/emails/{id}": { "get": { "tags": [ "Emails" ], "summary": "Retrieve an email", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Email id" } ], "operationId": "getEmailsById", "description": "Returns the email with its current status (`queued`, `scheduled`, `sent`, `delivered`, `delivery_delayed`, `bounced`, `complained`, `canceled` or `failed`) and its recipients." }, "patch": { "tags": [ "Emails" ], "summary": "Reschedule a scheduled email", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "email" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Email id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmailRequest" } } } }, "operationId": "patchEmailsById", "description": "Moves a scheduled email to another time. Only emails that are still scheduled can change." } }, "/emails/{id}/events": { "get": { "tags": [ "Emails" ], "summary": "Delivery events and per-recipient status", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailEvents" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Email id" } ], "operationId": "getEmailsByIdEvents", "description": "Every delivery event of the email (sent, delivered, delayed, bounced, complained, opened, clicked, failed) and the status of each recipient." } }, "/emails/{id}/cancel": { "post": { "tags": [ "Emails" ], "summary": "Cancel a scheduled email", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "email" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Email id" } ], "operationId": "postEmailsByIdCancel", "description": "Cancels an email that was sent with `scheduled_at` and has not gone out yet." } }, "/domains": { "post": { "tags": [ "Domains" ], "summary": "Add a domain", "responses": { "201": { "description": "Created, with the DNS records to publish", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainRequest" } } } }, "operationId": "postDomains", "description": "Adds a sending domain and returns the DNS records to publish: a DKIM TXT record, the return-path (`send.` by default) MX and SPF records, and optional tracking and receiving records. Verification starts automatically once the records are published." }, "get": { "tags": [ "Domains" ], "summary": "List domains", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getDomains" } }, "/domains/{id}": { "get": { "tags": [ "Domains" ], "summary": "Retrieve a domain", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain id" } ], "operationId": "getDomainsById" }, "patch": { "tags": [ "Domains" ], "summary": "Update tracking or TLS settings", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "domain" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDomainRequest" } } } }, "operationId": "patchDomainsById" }, "delete": { "tags": [ "Domains" ], "summary": "Delete a domain", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "domain" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain id" } ], "operationId": "deleteDomainsById" } }, "/domains/{id}/verify": { "post": { "tags": [ "Domains" ], "summary": "Check the DNS records now and keep re-checking", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "domain" }, "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "object", "id", "status" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain id" } ], "operationId": "postDomainsByIdVerify", "description": "Checks the domain's DNS records now and keeps re-checking in the background until it is verified or fails." } }, "/domains/{id}/dns-provider": { "get": { "tags": [ "Domains" ], "summary": "Detect the DNS host (Cloudflare or other) and the zone holding the records", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "dns_provider" }, "zone": { "type": "string" }, "provider": { "type": "string", "enum": [ "cloudflare", "other", "unknown" ] }, "nameservers": { "type": "array", "items": { "type": "string" } }, "cloudflare_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "object", "zone", "provider", "nameservers", "cloudflare_url" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain id" } ], "operationId": "getDomainsByIdDnsProvider" } }, "/domains/{id}/domain-connect": { "get": { "tags": [ "Domains" ], "summary": "Is one-click DNS setup (Domain Connect) available at this domain's DNS host?", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "domain_connect" }, "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ], "enum": [ "not_configured", "no_domain_connect", "template_not_supported", null ] }, "dns_host": { "type": [ "string", "null" ] }, "zone": { "type": [ "string", "null" ] } }, "required": [ "object", "available", "reason", "dns_host", "zone" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain id" } ], "operationId": "getDomainsByIdDomainConnect" }, "post": { "tags": [ "Domains" ], "summary": "Start Domain Connect: get the signed URL to send the user to their DNS host", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "domain_connect" }, "id": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "object", "id", "url" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Domain id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_uri": { "type": "string", "format": "uri" } }, "required": [] } } } }, "operationId": "postDomainsByIdDomainConnect", "description": "Starts one-click DNS setup with Domain Connect: returns a signed URL that sends the user to their DNS host to approve the records." } }, "/api-keys": { "post": { "tags": [ "API Keys" ], "summary": "Create an API key", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string", "description": "Shown once. Starts with ht_" } }, "required": [ "id", "token" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "operationId": "postApiKeys", "description": "Creates an API key. The full `token` is returned only in this response; store it securely. Scopes are `:read|write|send`, `:*` or `*` (`write` includes `read`); `domain_id` restricts an email key to one sending domain." }, "get": { "tags": [ "API Keys" ], "summary": "List API keys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getApiKeys" } }, "/api-keys/{id}": { "delete": { "tags": [ "API Keys" ], "summary": "Revoke an API key", "responses": { "200": { "description": "Revoked" }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "API key id" } ], "operationId": "deleteApiKeysById", "description": "Revokes the key at once. Requests with it fail with `401` from then on." } }, "/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook endpoint", "responses": { "201": { "description": "Created, includes signing_secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "operationId": "postWebhooks", "description": "Registers an HTTPS endpoint for the events you choose. The response includes the signing secret (`whsec_…`) used to verify deliveries." }, "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getWebhooks" } }, "/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieve a webhook", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id" } ], "operationId": "getWebhooksById" }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "operationId": "patchWebhooksById" }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id" } ], "operationId": "deleteWebhooksById" } }, "/webhooks/{id}/rotate": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate the signing secret (old secret stays valid 24h)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "secret" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id" } ], "operationId": "postWebhooksByIdRotate", "description": "Issues a new signing secret. Deliveries are signed with both the old and the new secret for 24 hours so you can roll over without downtime." } }, "/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Recent delivery attempts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook id" } ], "operationId": "getWebhooksByIdDeliveries" } }, "/webhooks/deliveries/{deliveryId}/replay": { "post": { "tags": [ "Webhooks" ], "summary": "Re-send a delivery with the same svix-id", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Delivery id" } ], "operationId": "postWebhooksDeliveriesByDeliveryIdReplay", "description": "Sends a past delivery again with the same `svix-id`, so a handler that de-duplicates by id treats it as the same event." } }, "/audiences": { "post": { "tags": [ "Audiences" ], "summary": "Create an audience", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAudienceRequest" } } } }, "operationId": "postAudiences" }, "get": { "tags": [ "Audiences" ], "summary": "List audiences", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Audience" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getAudiences" } }, "/audiences/{id}": { "get": { "tags": [ "Audiences" ], "summary": "Retrieve an audience", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Audience id" } ], "operationId": "getAudiencesById" }, "delete": { "tags": [ "Audiences" ], "summary": "Delete an audience and its contacts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "audience" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Audience id" } ], "operationId": "deleteAudiencesById" } }, "/audiences/{id}/contacts": { "post": { "tags": [ "Contacts" ], "summary": "Create or update a contact", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "contact" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Audience id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRequest" } } } }, "operationId": "postAudiencesByIdContacts", "description": "Creates a contact in the audience, or updates the existing one with this email." }, "get": { "tags": [ "Contacts" ], "summary": "List contacts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Audience id" } ], "operationId": "getAudiencesByIdContacts" } }, "/audiences/{id}/contacts/{contact}": { "get": { "tags": [ "Contacts" ], "summary": "Retrieve a contact by id or email", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Audience id" }, { "name": "contact", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email" } ], "operationId": "getAudiencesByIdContactsByContact" }, "patch": { "tags": [ "Contacts" ], "summary": "Update a contact", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "contact" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Audience id" }, { "name": "contact", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" } } } }, "operationId": "patchAudiencesByIdContactsByContact" }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "contact" }, "contact": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "contact", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Audience id" }, { "name": "contact", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email" } ], "operationId": "deleteAudiencesByIdContactsByContact" } }, "/broadcasts": { "post": { "tags": [ "Broadcasts" ], "summary": "Create a broadcast draft", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "broadcast" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBroadcastRequest" } } } }, "operationId": "postBroadcasts", "description": "Creates a broadcast draft for an audience or segment. Send it with `POST /broadcasts/{id}/send`." }, "get": { "tags": [ "Broadcasts" ], "summary": "List broadcasts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getBroadcasts" } }, "/broadcasts/{id}": { "get": { "tags": [ "Broadcasts" ], "summary": "Retrieve a broadcast", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Broadcast id" } ], "operationId": "getBroadcastsById" }, "patch": { "tags": [ "Broadcasts" ], "summary": "Update a draft or scheduled broadcast", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "broadcast" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Broadcast id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBroadcastRequest" } } } }, "operationId": "patchBroadcastsById" }, "delete": { "tags": [ "Broadcasts" ], "summary": "Delete a broadcast", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "broadcast" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Broadcast id" } ], "operationId": "deleteBroadcastsById" } }, "/broadcasts/{id}/send": { "post": { "tags": [ "Broadcasts" ], "summary": "Send now or schedule", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "broadcast" }, "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "object", "id", "status" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Broadcast id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendBroadcastRequest" } } } }, "operationId": "postBroadcastsByIdSend", "description": "Sends the broadcast now, or at `scheduled_at`. Contacts who unsubscribed are skipped; with a topic, only contacts subscribed to it receive the broadcast." } }, "/broadcasts/{id}/cancel": { "post": { "tags": [ "Broadcasts" ], "summary": "Cancel a scheduled broadcast", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "broadcast" }, "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "object", "id", "status" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Broadcast id" } ], "operationId": "postBroadcastsByIdCancel" } }, "/templates": { "post": { "tags": [ "Templates" ], "summary": "Create a template (draft)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "template" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateRequest" } } } }, "operationId": "postTemplates" }, "get": { "tags": [ "Templates" ], "summary": "List templates", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateSummary" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Return emails older than this id" }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "folder", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published" ] } } ], "operationId": "getTemplates" } }, "/templates/{id}": { "get": { "tags": [ "Templates" ], "summary": "Retrieve a template by id or alias", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "operationId": "getTemplatesById" }, "patch": { "tags": [ "Templates" ], "summary": "Update the draft of a template", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "template" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateRequest" } } } }, "operationId": "patchTemplatesById" }, "delete": { "tags": [ "Templates" ], "summary": "Delete a template", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "template" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "operationId": "deleteTemplatesById" } }, "/templates/{id}/publish": { "post": { "tags": [ "Templates" ], "summary": "Publish the draft; sends use the published version", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "template" }, "id": { "type": "string" }, "current_version_id": { "type": "string" } }, "required": [ "object", "id", "current_version_id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "operationId": "postTemplatesByIdPublish", "description": "Publishes the template's draft. Emails that reference the template use the published version until you publish again." } }, "/templates/{id}/duplicate": { "post": { "tags": [ "Templates" ], "summary": "Copy a template as a new draft", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "template" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id or alias" } ], "operationId": "postTemplatesByIdDuplicate" } }, "/emails/metrics": { "get": { "tags": [ "Metrics" ], "summary": "Email metrics per period (and domain): counts and rates", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMetrics" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "start_date", "in": "query", "schema": { "type": "string" }, "description": "ISO date or datetime; default end_date − 6 days" }, { "name": "end_date", "in": "query", "schema": { "type": "string" }, "description": "Default now" }, { "name": "timezone", "in": "query", "schema": { "type": "string" }, "description": "IANA, default UTC" }, { "name": "granularity", "in": "query", "schema": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly" ] } }, { "name": "metrics", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated: sent, delivered, delivery_delayed, failed, suppressed, bounced, opened, unique_opened, clicked, unique_clicked, complained, unsubscribed, received, delivery_rate, open_rate, click_rate, bounce_rate, complaint_rate, unsubscribe_rate" }, { "name": "dimensions", "in": "query", "schema": { "type": "string" }, "description": "period (default) and/or domain" }, { "name": "domain_id", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated domain ids" } ], "operationId": "getEmailsMetrics" } }, "/logs": { "get": { "tags": [ "Logs" ], "summary": "API request logs, newest first", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RequestLog" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Return emails older than this id" }, { "name": "before", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "2xx", "4xx", "5xx", "error" ] } }, { "name": "method", "in": "query", "schema": { "type": "string" }, "description": "GET, POST…" }, { "name": "endpoint", "in": "query", "schema": { "type": "string" }, "description": "Path contains" }, { "name": "api_key_id", "in": "query", "schema": { "type": "string" }, "description": "Only this key" }, { "name": "user_agent", "in": "query", "schema": { "type": "string" }, "description": "User agent contains" }, { "name": "since", "in": "query", "schema": { "type": "string" }, "description": "ISO datetime" }, { "name": "until", "in": "query", "schema": { "type": "string" }, "description": "ISO datetime" } ], "operationId": "getLogs", "description": "Your API requests, newest first, with method, path, status and timing. Request and response bodies are on the single-log endpoint, with secrets redacted." } }, "/logs/{id}": { "get": { "tags": [ "Logs" ], "summary": "One request log with its request and response bodies (secrets redacted)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestLogDetail" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Log id" } ], "operationId": "getLogsById" } }, "/usage": { "get": { "tags": [ "Usage" ], "summary": "What the business used against its limits", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getUsage", "description": "What the business used against its plan's limits: emails, domains, contacts, templates and automation runs." } }, "/contacts": { "post": { "tags": [ "Contacts" ], "summary": "Create a contact (or update the one with that email)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "contact" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRequest" } } } }, "operationId": "postContacts", "description": "Creates a contact, or updates the one that already has this email. Contacts are shared across audiences, segments and topics." }, "get": { "tags": [ "Contacts" ], "summary": "List contacts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Return emails older than this id" }, { "name": "segment_id", "in": "query", "schema": { "type": "string" }, "description": "Only members of this segment" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search email or name" } ], "operationId": "getContacts" } }, "/contacts/{id}": { "get": { "tags": [ "Contacts" ], "summary": "Retrieve a contact by id or email", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email" } ], "operationId": "getContactsById" }, "patch": { "tags": [ "Contacts" ], "summary": "Update a contact", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "contact" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" } } } }, "operationId": "patchContactsById" }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "contact" }, "contact": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "contact", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email" } ], "operationId": "deleteContactsById" } }, "/contacts/{id}/segments": { "get": { "tags": [ "Contacts" ], "summary": "Segments the contact belongs to", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email" } ], "operationId": "getContactsByIdSegments" } }, "/contacts/{id}/segments/{segment}": { "post": { "tags": [ "Contacts" ], "summary": "Add the contact to a segment", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "contact_id": { "type": "string" }, "segment_id": { "type": "string" } }, "required": [ "object", "contact_id", "segment_id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email" }, { "name": "segment", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Segment id" } ], "operationId": "postContactsByIdSegmentsBySegment" }, "delete": { "tags": [ "Contacts" ], "summary": "Remove the contact from a segment", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "contact_id": { "type": "string" }, "segment_id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "contact_id", "segment_id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email" }, { "name": "segment", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Segment id" } ], "operationId": "deleteContactsByIdSegmentsBySegment" } }, "/contacts/{id}/topics": { "get": { "tags": [ "Contacts" ], "summary": "The contact's subscription to every topic", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactTopic" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email" } ], "operationId": "getContactsByIdTopics" }, "patch": { "tags": [ "Contacts" ], "summary": "Set the contact's topic subscriptions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "contact" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact id or email" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactTopicsRequest" } } } }, "operationId": "patchContactsByIdTopics" } }, "/segments": { "post": { "tags": [ "Segments" ], "summary": "Create a segment", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentRequest" } } } }, "operationId": "postSegments" }, "get": { "tags": [ "Segments" ], "summary": "List segments", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getSegments" } }, "/segments/{id}": { "get": { "tags": [ "Segments" ], "summary": "Retrieve a segment with its contact count", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Segment id" } ], "operationId": "getSegmentsById" }, "patch": { "tags": [ "Segments" ], "summary": "Rename a segment", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Segment id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentRequest" } } } }, "operationId": "patchSegmentsById" }, "delete": { "tags": [ "Segments" ], "summary": "Delete a segment (its contacts stay)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "segment" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Segment id" } ], "operationId": "deleteSegmentsById" } }, "/segments/{id}/contacts": { "get": { "tags": [ "Segments" ], "summary": "Contacts in a segment", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Segment id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Return emails older than this id" } ], "operationId": "getSegmentsByIdContacts" } }, "/topics": { "post": { "tags": [ "Topics" ], "summary": "Create a topic", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topic" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTopicRequest" } } } }, "operationId": "postTopics" }, "get": { "tags": [ "Topics" ], "summary": "List topics", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Topic" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getTopics" } }, "/topics/{id}": { "get": { "tags": [ "Topics" ], "summary": "Retrieve a topic", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topic" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Topic id" } ], "operationId": "getTopicsById" }, "patch": { "tags": [ "Topics" ], "summary": "Update a topic's name, description or visibility", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topic" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Topic id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTopicRequest" } } } }, "operationId": "patchTopicsById" }, "delete": { "tags": [ "Topics" ], "summary": "Delete a topic", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "topic" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Topic id" } ], "operationId": "deleteTopicsById" } }, "/contact-properties": { "post": { "tags": [ "Contact properties" ], "summary": "Declare a contact property", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProperty" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactPropertyRequest" } } } }, "operationId": "postContactProperties" }, "get": { "tags": [ "Contact properties" ], "summary": "List contact properties", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactProperty" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getContactProperties" } }, "/contact-properties/{id}": { "patch": { "tags": [ "Contact properties" ], "summary": "Change a property's fallback value", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactProperty" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Property id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactPropertyRequest" } } } }, "operationId": "patchContactPropertiesById" }, "delete": { "tags": [ "Contact properties" ], "summary": "Delete a property and its values", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "contact_property" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Property id" } ], "operationId": "deleteContactPropertiesById" } }, "/events": { "post": { "tags": [ "Events" ], "summary": "Define a custom event (name and payload schema)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventDef" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventRequest" } } } }, "operationId": "postEvents" }, "get": { "tags": [ "Events" ], "summary": "List event definitions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventDef" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getEvents" } }, "/events/send": { "post": { "tags": [ "Events" ], "summary": "Send an event for a contact: starts automations triggered by it and resumes runs waiting for it", "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "event" }, "event": { "type": "string" }, "contact_id": { "type": "string" }, "runs_started": { "type": "integer" }, "runs_resumed": { "type": "integer" } }, "required": [ "object", "event", "contact_id", "runs_started", "runs_resumed" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEventRequest" } } } }, "operationId": "postEventsSend", "description": "Records an event for a contact: automations triggered by this event start, and runs waiting for it resume." } }, "/events/{id}": { "get": { "tags": [ "Events" ], "summary": "Retrieve an event definition by id or name", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventDef" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Event id or name" } ], "operationId": "getEventsById" }, "patch": { "tags": [ "Events" ], "summary": "Change an event's payload schema", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventDef" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Event id or name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventRequest" } } } }, "operationId": "patchEventsById" }, "delete": { "tags": [ "Events" ], "summary": "Delete an event definition", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "event" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Event id or name" } ], "operationId": "deleteEventsById" } }, "/automations": { "post": { "tags": [ "Automations" ], "summary": "Create an automation (steps and connections)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "automation" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAutomationRequest" } } } }, "operationId": "postAutomations" }, "get": { "tags": [ "Automations" ], "summary": "List automations", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getAutomations" } }, "/automations/{id}": { "get": { "tags": [ "Automations" ], "summary": "Retrieve an automation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Automation id" } ], "operationId": "getAutomationsById" }, "patch": { "tags": [ "Automations" ], "summary": "Update an automation; steps can only change while it is disabled", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Automation id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutomationRequest" } } } }, "operationId": "patchAutomationsById" }, "delete": { "tags": [ "Automations" ], "summary": "Delete an automation and its runs", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "automation" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Automation id" } ], "operationId": "deleteAutomationsById" } }, "/automations/{id}/stop": { "post": { "tags": [ "Automations" ], "summary": "Disable the automation and cancel its runs in flight", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Automation id" } ], "operationId": "postAutomationsByIdStop" } }, "/automations/{id}/duplicate": { "post": { "tags": [ "Automations" ], "summary": "Copy an automation as a new disabled one", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "automation" }, "id": { "type": "string" } }, "required": [ "object", "id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Automation id" } ], "operationId": "postAutomationsByIdDuplicate" } }, "/automations/{id}/runs": { "get": { "tags": [ "Automations" ], "summary": "Runs of an automation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRun" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Automation id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Return emails older than this id" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated: running, waiting, completed, failed, cancelled, skipped" } ], "operationId": "getAutomationsByIdRuns" } }, "/automations/{id}/runs/{run_id}": { "get": { "tags": [ "Automations" ], "summary": "One run with its steps", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRun" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (10 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Automation id" }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run id" } ], "operationId": "getAutomationsByIdRunsByRun_id" } }, "/chat/sites": { "post": { "tags": [ "Chat sites" ], "summary": "Add an extra chat site on a subdomain (the domain's own widget is created automatically)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSite" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSiteRequest" } } } }, "operationId": "postChatSites" }, "get": { "tags": [ "Chat sites" ], "summary": "List chat sites", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatSite" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatSites" } }, "/chat/sites/{id}": { "get": { "tags": [ "Chat sites" ], "summary": "Retrieve a site", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSite" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" } ], "operationId": "getChatSitesById" }, "patch": { "tags": [ "Chat sites" ], "summary": "Update a site's settings, origins or status", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSite" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSiteUpdate" } } } }, "operationId": "patchChatSitesById" }, "delete": { "tags": [ "Chat sites" ], "summary": "Delete a site and everything under it", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_site" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" } ], "operationId": "deleteChatSitesById" } }, "/chat/sites/{id}/identity-secret": { "post": { "tags": [ "Chat sites" ], "summary": "Rotate the secret used to sign identify() calls", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" } }, "required": [ "secret" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" } ], "operationId": "postChatSitesByIdIdentitySecret", "description": "Rotates the secret used to sign `identify` calls (HMAC-SHA256 of the user id). Signatures made with the old secret stop working at once." } }, "/chat/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List conversations", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatConversation" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated: open,pending,resolved,closed" }, { "name": "assignee_id", "in": "query", "schema": { "type": "string" } }, { "name": "site_id", "in": "query", "schema": { "type": "string" } }, { "name": "visitor_id", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } } ], "operationId": "getChatConversations", "description": "Conversations across every channel, newest activity first. Filter by status, assignee, site, visitor or a search query; page with `after`." } }, "/chat/conversations/{id}": { "get": { "tags": [ "Conversations" ], "summary": "Retrieve a conversation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatConversation" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation id" } ], "operationId": "getChatConversationsById" }, "patch": { "tags": [ "Conversations" ], "summary": "Assign, change status or replace tags", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatConversation" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatConversationUpdate" } } } }, "operationId": "patchChatConversationsById", "description": "Assigns the conversation, changes its status (`open`, `pending`, `resolved`, `closed`) or replaces its tags." } }, "/chat/conversations/{id}/messages": { "get": { "tags": [ "Conversations" ], "summary": "Timeline (messages and events) of a conversation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatTimelineItem" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation id" }, { "name": "after_seq", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } }, { "name": "include_private", "in": "query", "schema": { "type": "boolean", "default": false } } ], "operationId": "getChatConversationsByIdMessages", "description": "The conversation's timeline: messages and events in order of `seq`. Pass `after_seq` to read only what is new; internal notes are included only with `include_private=true`." }, "post": { "tags": [ "Conversations" ], "summary": "Send a message as your team (Idempotency-Key supported)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_message" }, "id": { "type": "string" }, "seq": { "type": "integer" }, "conversation_id": { "type": "string" }, "duplicate": { "type": "boolean" } }, "required": [ "object", "id", "seq", "conversation_id", "duplicate" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation id" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMessageRequest" } } } }, "operationId": "postChatConversationsByIdMessages", "description": "Posts a message as your team. It is delivered on the conversation's channel (widget, Zalo, Messenger, email…). Send `Idempotency-Key` (used as the message's `client_id`): a retry with the same key returns the first message with `duplicate: true`." } }, "/chat/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers (one person across channels)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCustomer" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "stage", "in": "query", "schema": { "type": "string", "enum": [ "new", "contacted", "qualified", "customer", "lost" ] } }, { "name": "owner_id", "in": "query", "schema": { "type": "string" } }, { "name": "label", "in": "query", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "schema": { "type": "string", "enum": [ "web", "zalo", "messenger", "email", "instagram", "tiktokshop", "zalo_personal", "tiktok", "whatsapp", "telegram", "x", "line" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "after", "in": "query", "schema": { "type": "string" } } ], "operationId": "getChatCustomers" } }, "/chat/customers/export.csv": { "get": { "tags": [ "Customers" ], "summary": "Export the matching customers as CSV", "responses": { "200": { "description": "CSV file", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "stage", "in": "query", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "schema": { "type": "string" } }, { "name": "label", "in": "query", "schema": { "type": "string" } } ], "operationId": "getChatCustomersExport.csv" } }, "/chat/customers/merge-suggestions": { "get": { "tags": [ "Customers" ], "summary": "Pairs of customers that share an e-mail or phone number", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "a": { "$ref": "#/components/schemas/ChatCustomer" }, "b": { "$ref": "#/components/schemas/ChatCustomer" }, "by": { "type": "string", "enum": [ "email", "phone" ] } }, "required": [ "a", "b", "by" ] } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatCustomersMergeSuggestions" } }, "/chat/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Retrieve a customer with their visitors", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCustomer" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Customer id" } ], "operationId": "getChatCustomersById" }, "patch": { "tags": [ "Customers" ], "summary": "Update contact details, owner, stage, labels or custom fields", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCustomer" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Customer id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCustomerUpdate" } } } }, "operationId": "patchChatCustomersById" } }, "/chat/customers/{id}/merge": { "post": { "tags": [ "Customers" ], "summary": "Merge another customer into this one", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCustomer" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Customer id that survives" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" } }, "required": [ "from" ] } } } }, "operationId": "postChatCustomersByIdMerge" } }, "/chat/customers/{id}/conversations": { "get": { "tags": [ "Customers" ], "summary": "A customer's conversations across all channels", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatConversation" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Customer id" } ], "operationId": "getChatCustomersByIdConversations" } }, "/chat/customer-fields": { "get": { "tags": [ "Customers" ], "summary": "List custom customer fields", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCustomerField" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatCustomerFields" }, "post": { "tags": [ "Customers" ], "summary": "Create a custom customer field", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCustomerField" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCustomerFieldRequest" } } } }, "operationId": "postChatCustomerFields" } }, "/chat/customer-fields/{id}": { "patch": { "tags": [ "Customers" ], "summary": "Update a custom customer field", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCustomerField" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Field id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCustomerFieldPatch" } } } }, "operationId": "patchChatCustomerFieldsById" }, "delete": { "tags": [ "Customers" ], "summary": "Delete a custom customer field", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_customer_field" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Field id" } ], "operationId": "deleteChatCustomerFieldsById" } }, "/chat/products": { "get": { "tags": [ "Products" ], "summary": "List catalog products", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatProduct" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "active", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "after", "in": "query", "schema": { "type": "string" } } ], "operationId": "getChatProducts" }, "post": { "tags": [ "Products" ], "summary": "Add a product", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatProduct" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatProductRequest" } } } }, "operationId": "postChatProducts" } }, "/chat/products/search": { "get": { "tags": [ "Products" ], "summary": "Relevance search over the catalog (accent-insensitive)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatProduct" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 5 } } ], "operationId": "getChatProductsSearch" } }, "/chat/products/categories": { "get": { "tags": [ "Products" ], "summary": "Distinct product categories", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatProductsCategories" } }, "/chat/products/import": { "post": { "tags": [ "Products" ], "summary": "Import products from CSV text, a CSV/Google Sheets link, or a website's schema.org Product JSON-LD", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_product_import" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "deactivated": { "type": "integer" }, "scanned": { "type": "integer" } }, "required": [ "object", "created", "updated", "deactivated", "scanned" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatProductImportRequest" } } } }, "operationId": "postChatProductsImport" } }, "/chat/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Retrieve a product", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatProduct" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product id" } ], "operationId": "getChatProductsById" }, "patch": { "tags": [ "Products" ], "summary": "Update a product", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatProduct" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatProductRequest" } } } }, "operationId": "patchChatProductsById" }, "delete": { "tags": [ "Products" ], "summary": "Delete a product", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_product" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product id" } ], "operationId": "deleteChatProductsById" } }, "/chat/conversations/{id}/products": { "post": { "tags": [ "Conversations" ], "summary": "Send product cards into a conversation", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_message" }, "id": { "type": "string" }, "seq": { "type": "integer" }, "conversation_id": { "type": "string" } }, "required": [ "object", "id", "seq", "conversation_id" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_ids": { "type": "array", "items": { "type": "string" } }, "intro": { "type": "string" } }, "required": [ "product_ids" ] } } } }, "operationId": "postChatConversationsByIdProducts" } }, "/chat/orders": { "get": { "tags": [ "Orders" ], "summary": "List orders", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatOrder" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "new", "consulting", "confirmed", "shipping", "done", "cancelled" ] } }, { "name": "customer_id", "in": "query", "schema": { "type": "string" } }, { "name": "conversation_id", "in": "query", "schema": { "type": "string" } }, { "name": "payment_status", "in": "query", "schema": { "type": "string", "enum": [ "unpaid", "paid" ] } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "after", "in": "query", "schema": { "type": "string" } } ], "operationId": "getChatOrders" }, "post": { "tags": [ "Orders" ], "summary": "Create an order (optionally from a conversation, posting an order card)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatOrder" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatOrderRequest" } } } }, "operationId": "postChatOrders" } }, "/chat/orders/stats": { "get": { "tags": [ "Orders" ], "summary": "Orders per stage and paid revenue", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_order_stats" }, "byStatus": { "type": "object" }, "paidTotal": { "type": "integer" }, "paidCount": { "type": "integer" } }, "required": [ "object", "byStatus", "paidTotal", "paidCount" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatOrdersStats" } }, "/chat/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Retrieve an order by id or code", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatOrder" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order id or code (DH000123)" } ], "operationId": "getChatOrdersById" }, "patch": { "tags": [ "Orders" ], "summary": "Update items, stage, address or note", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatOrder" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatOrderUpdate" } } } }, "operationId": "patchChatOrdersById" } }, "/chat/orders/{id}/payment-link": { "post": { "tags": [ "Orders" ], "summary": "Create a VietQR payment for the order and post it into the conversation", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatPaymentLink" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatPaymentLinkRequest" } } } }, "operationId": "postChatOrdersByIdPaymentLink" } }, "/chat/zns/templates": { "get": { "tags": [ "ZNS" ], "summary": "Approved ZNS templates of a Zalo OA account (with the daily quota)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatZnsTemplate" } }, "quota": { "type": [ "object", "null" ] } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "operationId": "getChatZnsTemplates" } }, "/chat/zns/templates/{id}": { "get": { "tags": [ "ZNS" ], "summary": "A ZNS template with its parameters", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatZnsTemplate" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Template id" }, { "name": "account_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "operationId": "getChatZnsTemplatesById" } }, "/chat/zns": { "get": { "tags": [ "ZNS" ], "summary": "ZNS messages sent by the team", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatZnsMessage" } }, "stats": { "type": "object" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "customer_id", "in": "query", "schema": { "type": "string" } }, { "name": "order_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "operationId": "getChatZns" }, "post": { "tags": [ "ZNS" ], "summary": "Send one ZNS template message to a phone number (billed by Zalo)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatZnsMessage" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatZnsSendRequest" } } } }, "operationId": "postChatZns" } }, "/chat/zns/bulk": { "post": { "tags": [ "ZNS" ], "summary": "Queue a ZNS template to every customer matching the filters (one message per customer with a phone)", "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_zns_bulk" }, "queued": { "type": "integer" }, "skipped": { "type": "integer" } }, "required": [ "object", "queued", "skipped" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatZnsBulkRequest" } } } }, "operationId": "postChatZnsBulk" } }, "/chat/reports": { "get": { "tags": [ "Reports and ratings" ], "summary": "Support report for a date range: overview, per-day, per-agent, channels, tags (defaults to the last 30 days)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatReport" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "site_id", "in": "query", "schema": { "type": "string" } }, { "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "name": "tz", "in": "query", "schema": { "type": "string", "default": "Asia/Ho_Chi_Minh" } } ], "operationId": "getChatReports" } }, "/chat/ratings": { "get": { "tags": [ "Reports and ratings" ], "summary": "CSAT ratings in a date range", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatRating" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "site_id", "in": "query", "schema": { "type": "string" } }, { "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "name": "tz", "in": "query", "schema": { "type": "string", "default": "Asia/Ho_Chi_Minh" } } ], "operationId": "getChatRatings" } }, "/chat/tickets": { "get": { "tags": [ "Tickets" ], "summary": "List tickets", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatTicket" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "in_progress", "waiting", "resolved", "closed" ] } }, { "name": "open", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "priority", "in": "query", "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "assignee_id", "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "schema": { "type": "string" } }, { "name": "conversation_id", "in": "query", "schema": { "type": "string" } }, { "name": "overdue", "in": "query", "schema": { "type": "string", "enum": [ "true" ] } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "after", "in": "query", "schema": { "type": "string" } } ], "operationId": "getChatTickets" }, "post": { "tags": [ "Tickets" ], "summary": "Create a ticket (SLA deadlines follow the team policy)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatTicket" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatTicketRequest" } } } }, "operationId": "postChatTickets" } }, "/chat/tickets/stats": { "get": { "tags": [ "Tickets" ], "summary": "Open, overdue, unassigned counts and this week's resolution figures", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_ticket_stats" }, "open": { "type": "integer" }, "overdue": { "type": "integer" }, "unassigned": { "type": "integer" }, "resolvedThisWeek": { "type": "integer" }, "breachedThisWeek": { "type": "integer" }, "avgResolveMinutes": { "type": [ "integer", "null" ] } }, "required": [ "object", "open", "overdue", "unassigned", "resolvedThisWeek", "breachedThisWeek", "avgResolveMinutes" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatTicketsStats" } }, "/chat/tickets/{id}": { "get": { "tags": [ "Tickets" ], "summary": "Retrieve a ticket by id or code (TK000123)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatTicket" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Ticket id or code" } ], "operationId": "getChatTicketsById" }, "patch": { "tags": [ "Tickets" ], "summary": "Update a ticket (status, priority, assignee, due date…)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatTicket" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Ticket id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatTicketUpdate" } } } }, "operationId": "patchChatTicketsById" }, "delete": { "tags": [ "Tickets" ], "summary": "Delete a ticket", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_ticket" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Ticket id" } ], "operationId": "deleteChatTicketsById" } }, "/chat/sla": { "get": { "tags": [ "Tickets" ], "summary": "The team's SLA policy (minutes per priority)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSlaPolicy" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatSla" }, "put": { "tags": [ "Tickets" ], "summary": "Replace the SLA policy", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSlaPolicy" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSlaPolicy" } } } }, "operationId": "putChatSla" } }, "/chat/profile-links": { "get": { "tags": [ "Chat sites" ], "summary": "The business's profile links (URL templates agents open for the person in a conversation)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatProfileLink" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatProfileLinks" }, "put": { "tags": [ "Chat sites" ], "summary": "Replace the profile links (max 10; https, known {{variables}}, none in the host)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatProfileLink" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatProfileLinksRequest" } } } }, "operationId": "putChatProfileLinks" } }, "/chat/flows": { "get": { "tags": [ "Flows" ], "summary": "List scripted flows", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatFlow" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatFlows" }, "post": { "tags": [ "Flows" ], "summary": "Create a scripted flow (trigger + steps)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatFlow" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatFlowRequest" } } } }, "operationId": "postChatFlows" } }, "/chat/flows/templates": { "get": { "tags": [ "Flows" ], "summary": "Ready-made flow templates", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatFlowTemplate" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatFlowsTemplates" } }, "/chat/flows/{id}": { "get": { "tags": [ "Flows" ], "summary": "Retrieve a flow", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatFlow" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Flow id" } ], "operationId": "getChatFlowsById" }, "patch": { "tags": [ "Flows" ], "summary": "Replace a flow's definition", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatFlow" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Flow id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatFlowRequest" } } } }, "operationId": "patchChatFlowsById" }, "delete": { "tags": [ "Flows" ], "summary": "Delete a flow", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_flow" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Flow id" } ], "operationId": "deleteChatFlowsById" } }, "/chat/conversations/{id}/flows/{flowId}": { "post": { "tags": [ "Conversations" ], "summary": "Start a flow in a conversation right now", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_flow_run" }, "conversation_id": { "type": "string" }, "flow_id": { "type": "string" }, "started": { "type": "boolean" } }, "required": [ "object", "conversation_id", "flow_id", "started" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation id" }, { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Flow id" } ], "operationId": "postChatConversationsByIdFlowsByFlowId" } }, "/chat/workflows": { "get": { "tags": [ "Workflows" ], "summary": "List workflows (event-driven automation)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatWorkflow" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatWorkflows" }, "post": { "tags": [ "Workflows" ], "summary": "Create a workflow: a trigger event, optional conditions and a list of steps", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatWorkflow" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatWorkflowRequest" } } } }, "operationId": "postChatWorkflows" } }, "/chat/workflows/templates": { "get": { "tags": [ "Workflows" ], "summary": "Ready-made workflow templates", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatWorkflowTemplate" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatWorkflowsTemplates" } }, "/chat/workflows/{id}": { "get": { "tags": [ "Workflows" ], "summary": "Retrieve a workflow", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatWorkflow" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow id" } ], "operationId": "getChatWorkflowsById" }, "patch": { "tags": [ "Workflows" ], "summary": "Replace a workflow's definition", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatWorkflow" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatWorkflowRequest" } } } }, "operationId": "patchChatWorkflowsById" }, "delete": { "tags": [ "Workflows" ], "summary": "Delete a workflow", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_workflow" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow id" } ], "operationId": "deleteChatWorkflowsById" } }, "/chat/workflows/{id}/runs": { "get": { "tags": [ "Workflows" ], "summary": "Recent runs of a workflow, with the log of each step", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatWorkflowRun" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "operationId": "getChatWorkflowsByIdRuns" } }, "/chat/conversations/{id}/workflows/{workflowId}": { "post": { "tags": [ "Conversations" ], "summary": "Run a workflow for a conversation now (its trigger conditions are skipped)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatWorkflowRun" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation id" }, { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workflow id" } ], "operationId": "postChatConversationsByIdWorkflowsByWorkflowId" } }, "/chat/conversations/{id}/workflows/stop": { "post": { "tags": [ "Conversations" ], "summary": "Stop every running or waiting workflow run in a conversation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_workflow_runs" }, "stopped": { "type": "integer" } }, "required": [ "object", "stopped" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation id" } ], "operationId": "postChatConversationsByIdWorkflowsStop" } }, "/chat/campaigns": { "get": { "tags": [ "Campaigns" ], "summary": "List widget campaigns", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCampaign" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "site_id", "in": "query", "schema": { "type": "string" } } ], "operationId": "getChatCampaigns" }, "post": { "tags": [ "Campaigns" ], "summary": "Create a campaign (proactive message or lead form)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCampaign" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCampaignRequest" } } } }, "operationId": "postChatCampaigns" } }, "/chat/campaigns/{id}": { "get": { "tags": [ "Campaigns" ], "summary": "Retrieve a campaign", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCampaign" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Campaign id" } ], "operationId": "getChatCampaignsById" }, "patch": { "tags": [ "Campaigns" ], "summary": "Update a campaign", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCampaign" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Campaign id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCampaignRequest" } } } }, "operationId": "patchChatCampaignsById" }, "delete": { "tags": [ "Campaigns" ], "summary": "Delete a campaign", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_campaign" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Campaign id" } ], "operationId": "deleteChatCampaignsById" } }, "/chat/live": { "get": { "tags": [ "Visitors" ], "summary": "Visitors currently on your sites", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatLiveVisitor" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatLive" } }, "/chat/live/greet": { "post": { "tags": [ "Visitors" ], "summary": "Start a conversation with a visitor who has not written yet", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatConversation" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatGreetRequest" } } } }, "operationId": "postChatLiveGreet" } }, "/chat/visitors/{id}": { "get": { "tags": [ "Visitors" ], "summary": "Retrieve a visitor", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatVisitor" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Visitor id" } ], "operationId": "getChatVisitorsById" }, "patch": { "tags": [ "Visitors" ], "summary": "Update a visitor's identity or custom data", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatVisitor" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Visitor id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatVisitorUpdate" } } } }, "operationId": "patchChatVisitorsById" }, "delete": { "tags": [ "Visitors" ], "summary": "Anonymise a visitor (GDPR-style delete)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_visitor" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Visitor id" } ], "operationId": "deleteChatVisitorsById" } }, "/chat/visitors/{id}/conversations": { "get": { "tags": [ "Visitors" ], "summary": "A visitor's conversations", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatConversation" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Visitor id" } ], "operationId": "getChatVisitorsByIdConversations" } }, "/chat/knowledge/documents": { "get": { "tags": [ "Knowledge" ], "summary": "List knowledge documents, in id order", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeDocument" } }, "has_more": { "type": "boolean" } }, "required": [ "object", "data", "has_more" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "collection", "in": "query", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "The last id of the previous page", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } } ], "operationId": "getChatKnowledgeDocuments" } }, "/chat/knowledge/documents/batch": { "post": { "tags": [ "Knowledge" ], "summary": "Create or update up to 100 documents", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeDocument" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBatchRequest" } } } }, "operationId": "postChatKnowledgeDocumentsBatch" } }, "/chat/knowledge/documents/{id}": { "get": { "tags": [ "Knowledge" ], "summary": "Get a knowledge document", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeDocument" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Your id for the document: 1–200 letters, digits or . _ : -", "schema": { "type": "string" } } ], "operationId": "getChatKnowledgeDocumentsById" }, "put": { "tags": [ "Knowledge" ], "summary": "Create or update a knowledge document under your own id; indexing runs in the background", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeDocument" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Your id for the document: 1–200 letters, digits or . _ : -", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeDocumentRequest" } } } }, "operationId": "putChatKnowledgeDocumentsById" }, "delete": { "tags": [ "Knowledge" ], "summary": "Delete a knowledge document", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "knowledge_document" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Your id for the document: 1–200 letters, digits or . _ : -", "schema": { "type": "string" } } ], "operationId": "deleteChatKnowledgeDocumentsById" } }, "/chat/knowledge/collections/{name}/sync": { "post": { "tags": [ "Knowledge" ], "summary": "Make a collection hold exactly these documents (up to 1,000): listed ones are written, the rest of the collection deleted", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeSync" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeSyncRequest" } } } }, "operationId": "postChatKnowledgeCollectionsByNameSync" } }, "/chat/knowledge/search": { "get": { "tags": [ "Knowledge" ], "summary": "Search the knowledge the assistant answers from, preferring a language", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeChunk" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "locale", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 6, "maximum": 20 } } ], "operationId": "getChatKnowledgeSearch" } }, "/chat/sites/{id}/kb/sources": { "get": { "tags": [ "Chat sites" ], "summary": "List the business's knowledge sources", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatKbSource" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" } ], "operationId": "getChatSitesByIdKbSources" }, "post": { "tags": [ "Chat sites" ], "summary": "Add a knowledge source (FAQ, text or website crawl); indexing runs in the background", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatKbSource" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatKbSourceRequest" } } } }, "operationId": "postChatSitesByIdKbSources" } }, "/chat/sites/{id}/kb/sources/{sourceId}": { "get": { "tags": [ "Chat sites" ], "summary": "Get a knowledge source", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatKbSource" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Source id" } ], "operationId": "getChatSitesByIdKbSourcesBySourceId" }, "patch": { "tags": [ "Chat sites" ], "summary": "Update a knowledge source and re-index it", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatKbSource" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Source id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatKbSourceRequest" } } } }, "operationId": "patchChatSitesByIdKbSourcesBySourceId" }, "delete": { "tags": [ "Chat sites" ], "summary": "Delete a knowledge source and its chunks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_kb_source" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Source id" } ], "operationId": "deleteChatSitesByIdKbSourcesBySourceId" } }, "/chat/sites/{id}/kb/sources/{sourceId}/reindex": { "post": { "tags": [ "Chat sites" ], "summary": "Re-index a knowledge source", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_kb_source" }, "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "object", "id", "status" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Source id" } ], "operationId": "postChatSitesByIdKbSourcesBySourceIdReindex" } }, "/chat/sites/{id}/kb/files": { "post": { "tags": [ "Chat sites" ], "summary": "Upload a PDF or DOCX as a knowledge source (multipart: file, optional title). Text is extracted on upload, up to 20 MB; scanned PDFs need OCR first.", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatKbSource" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "title": { "type": "string" } } } } } }, "operationId": "postChatSitesByIdKbFiles" } }, "/chat/sites/{id}/kb/search": { "get": { "tags": [ "Chat sites" ], "summary": "Search the knowledge base the assistant answers from (keyword and semantic matches, fused by rank)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatKbChunk" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 6 } } ], "operationId": "getChatSitesByIdKbSearch" } }, "/chat/subscriptions": { "get": { "tags": [ "Chat sites" ], "summary": "List subscriptions (web, App Store, Google Play); filter by external_user_id, platform, status (comma-separated)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatSubscription" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "external_user_id", "in": "query", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "schema": { "type": "string", "enum": [ "web", "ios", "android" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "operationId": "getChatSubscriptions" } }, "/chat/subscriptions/{platform}/{original_id}": { "put": { "tags": [ "Chat sites" ], "summary": "Create or update a subscription from your backend (App Store and Google Play ones also arrive from the stores once connected)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSubscription" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "web", "ios", "android" ] } }, { "name": "original_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Your or the store's subscription id (Apple originalTransactionId, Play purchase token)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSubscriptionRequest" } } } }, "operationId": "putChatSubscriptionsByPlatformByOriginal_id" } }, "/chat/customers/{id}/subscriptions": { "get": { "tags": [ "Customers" ], "summary": "A customer's subscriptions, newest first", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatSubscription" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Customer id" } ], "operationId": "getChatCustomersByIdSubscriptions" } }, "/chat/customers/{id}/purchases": { "get": { "tags": [ "Customers" ], "summary": "A customer's one-time in-app purchases (consumable, non-consumable, non-renewing), verified with the App Store or Google Play, newest first", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatStorePurchase" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Customer id" } ], "operationId": "getChatCustomersByIdPurchases" } }, "/chat/subscriptions/{id}/refresh": { "post": { "tags": [ "Chat sites" ], "summary": "Ask the App Store / Google Play about one subscription again (needs the app's App Store Server API key or Play service account)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSubscription" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Subscription id" } ], "operationId": "postChatSubscriptionsByIdRefresh" } }, "/chat/subscriptions/import": { "post": { "tags": [ "Chat sites" ], "summary": "Import existing subscribers of an app: Apple transaction ids (any of the customer's; their one-time purchases come too) or Google Play purchase tokens, up to 500 per call", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatSubscription" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app_id": { "type": "string" }, "ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "app_id", "ids" ] } } } }, "operationId": "postChatSubscriptionsImport" } }, "/chat/sites/{id}/purchase-token": { "get": { "tags": [ "Chat sites" ], "summary": "The app account token of one of your users: pass it as Apple appAccountToken / Google obfuscatedExternalAccountId when buying", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "purchase_token" }, "site_id": { "type": "string" }, "user_id": { "type": "string" }, "token": { "type": "string" } }, "required": [ "object", "site_id", "user_id", "token" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id" }, { "name": "user_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "operationId": "getChatSitesByIdPurchaseToken" } }, "/chat/canned-responses": { "get": { "tags": [ "Canned responses" ], "summary": "List canned responses", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCanned" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatCannedResponses" }, "post": { "tags": [ "Canned responses" ], "summary": "Create a canned response", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCanned" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCannedRequest" } } } }, "operationId": "postChatCannedResponses" } }, "/chat/routing-rules": { "get": { "tags": [ "Routing rules" ], "summary": "List distribution rules (evaluated top-down by position)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatRoutingRule" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getChatRoutingRules" }, "post": { "tags": [ "Routing rules" ], "summary": "Create a distribution rule", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRoutingRule" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRoutingRuleRequest" } } } }, "operationId": "postChatRoutingRules" } }, "/chat/routing-rules/reorder": { "post": { "tags": [ "Routing rules" ], "summary": "Reorder distribution rules", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatRoutingRule" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "ids" ] } } } }, "operationId": "postChatRoutingRulesReorder" } }, "/chat/routing-rules/{id}": { "patch": { "tags": [ "Routing rules" ], "summary": "Update a distribution rule", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRoutingRule" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Rule id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRoutingRuleRequest" } } } }, "operationId": "patchChatRoutingRulesById" }, "delete": { "tags": [ "Routing rules" ], "summary": "Delete a distribution rule", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_routing_rule" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Rule id" } ], "operationId": "deleteChatRoutingRulesById" } }, "/chat/canned-responses/{id}": { "patch": { "tags": [ "Canned responses" ], "summary": "Update a canned response", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCanned" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canned response id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCannedRequest" } } } }, "operationId": "patchChatCannedResponsesById" }, "delete": { "tags": [ "Canned responses" ], "summary": "Delete a canned response", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_canned_response" }, "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "object", "id", "deleted" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (50 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canned response id" } ], "operationId": "deleteChatCannedResponsesById" } }, "/payments": { "post": { "tags": [ "Payments" ], "summary": "Create a payment (Idempotency-Key supported)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" } } } }, "operationId": "postPayments" }, "get": { "tags": [ "Payments" ], "summary": "List payments", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated statuses" }, { "name": "connection_id", "in": "query", "schema": { "type": "string" } } ], "operationId": "getPayments" } }, "/payments/{id}": { "get": { "tags": [ "Payments" ], "summary": "Retrieve a payment", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment id" } ], "operationId": "getPaymentsById" } }, "/payments/{id}/ipn-deliveries": { "get": { "tags": [ "Payments" ], "summary": "IPN calls made for this payment (newest first)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/IpnDelivery" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment id" } ], "operationId": "getPaymentsByIdIpnDeliveries" } }, "/payments/{id}/cancel": { "post": { "tags": [ "Payments" ], "summary": "Cancel a pending payment", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment id" } ], "operationId": "postPaymentsByIdCancel" } }, "/payments/{id}/mark-paid": { "post": { "tags": [ "Payments" ], "summary": "Record money received outside the bank feed", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkPaidRequest" } } } }, "operationId": "postPaymentsByIdMarkPaid" } }, "/payments/qr": { "get": { "tags": [ "Payments" ], "summary": "VietQR for any amount and description (webhook-only integrations; nothing is stored)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VietQr" } }, "image/svg+xml": { "schema": { "type": "string" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "connection_id", "in": "query", "schema": { "type": "string" } }, { "name": "amount", "in": "query", "schema": { "type": "integer" } }, { "name": "content", "in": "query", "schema": { "type": "string", "maxLength": 50 } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "svg" ], "default": "json" } }, { "name": "logo", "in": "query", "description": "`0` leaves the hatang mark out of the SVG", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "1" } } ], "operationId": "getPaymentsQr" } }, "/payments/simulate/transfer": { "post": { "tags": [ "Payments" ], "summary": "Simulate a bank transfer (development only)", "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulatedTransfer" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateTransferRequest" } } } }, "operationId": "postPaymentsSimulateTransfer" } }, "/payments/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List bank transactions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "connection_id", "in": "query", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "in", "out" ] } }, { "name": "match_status", "in": "query", "schema": { "type": "string", "enum": [ "matched", "unmatched", "ignored" ] } }, { "name": "payment_id", "in": "query", "schema": { "type": "string" }, "description": "Only the transactions that settled this payment" } ], "operationId": "getPaymentsTransactions" } }, "/payments/transactions/{id}": { "get": { "tags": [ "Transactions" ], "summary": "Retrieve a transaction", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Transaction id" } ], "operationId": "getPaymentsTransactionsById" } }, "/payments/bank-connections": { "get": { "tags": [ "Bank connections" ], "summary": "List linked bank accounts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankConnection" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getPaymentsBankConnections" }, "post": { "tags": [ "Bank connections" ], "summary": "Start linking a bank account; the bank texts a code to the holder", "responses": { "201": { "description": "Created, waiting for the code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankConnection" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBankConnectionRequest" } } } }, "operationId": "postPaymentsBankConnections" } }, "/payments/bank-connections/{id}": { "get": { "tags": [ "Bank connections" ], "summary": "Retrieve a bank connection", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankConnection" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "operationId": "getPaymentsBankConnectionsById" }, "patch": { "tags": [ "Bank connections" ], "summary": "Change the label or matching settings", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankConnection" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBankConnectionRequest" } } } }, "operationId": "patchPaymentsBankConnectionsById" } }, "/payments/bank-connections/{id}/confirm": { "post": { "tags": [ "Bank connections" ], "summary": "Confirm linking with the code", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankConnection" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOtpRequest" } } } }, "operationId": "postPaymentsBankConnectionsByIdConfirm" } }, "/payments/bank-connections/{id}/unlink": { "post": { "tags": [ "Bank connections" ], "summary": "Start unlinking; returns a challenge when the bank confirms with a code", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankConnection" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "operationId": "postPaymentsBankConnectionsByIdUnlink" } }, "/payments/bank-connections/{id}/unlink/confirm": { "post": { "tags": [ "Bank connections" ], "summary": "Confirm unlinking with the code", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankConnection" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOtpRequest" } } } }, "operationId": "postPaymentsBankConnectionsByIdUnlinkConfirm" } }, "/payments/bank-connections/{id}/acb/notification": { "post": { "tags": [ "Bank connections" ], "summary": "ACB: register the transaction-notification service (a code follows)", "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcbNotificationChallenge" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcbNotificationSettingsRequest" } } } }, "operationId": "postPaymentsBankConnectionsByIdAcbNotification" }, "put": { "tags": [ "Bank connections" ], "summary": "ACB: change which transactions are notified (a code follows)", "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcbNotificationChallenge" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcbNotificationSettingsRequest" } } } }, "operationId": "putPaymentsBankConnectionsByIdAcbNotification" }, "delete": { "tags": [ "Bank connections" ], "summary": "ACB: cancel the notification service (a code follows)", "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcbNotificationChallenge" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "operationId": "deletePaymentsBankConnectionsByIdAcbNotification" }, "get": { "tags": [ "Bank connections" ], "summary": "ACB: what the holder has registered", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcbNotification" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "operationId": "getPaymentsBankConnectionsByIdAcbNotification" } }, "/payments/bank-connections/{id}/acb/notification/confirm": { "post": { "tags": [ "Bank connections" ], "summary": "ACB: confirm a notification registration, change or cancellation with the code", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcbNotificationConfirmed" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOtpRequest" } } } }, "operationId": "postPaymentsBankConnectionsByIdAcbNotificationConfirm" } }, "/payments/bank-connections/{id}/acb/virtual-accounts": { "get": { "tags": [ "Bank connections" ], "summary": "ACB: the virtual accounts under this account", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcbVirtualAccounts" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" }, { "name": "virtual_account_number", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "operationId": "getPaymentsBankConnectionsByIdAcbVirtualAccounts" } }, "/payments/acb/virtual-accounts": { "get": { "tags": [ "Bank connections" ], "summary": "ACB: the virtual accounts an account already has, before it is linked — pick one in config.acb.virtual_account_number to adopt it instead of opening another", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcbVirtualAccounts" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "account_number", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{6,20}$" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "operationId": "getPaymentsAcbVirtualAccounts" } }, "/payments/acb/notifications": { "get": { "tags": [ "Bank connections" ], "summary": "ACB: every account registered for notifications under this partner", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcbNotifications" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "operationId": "getPaymentsAcbNotifications" } }, "/payments/statements": { "post": { "tags": [ "Transactions" ], "summary": "Import a bank statement (CSV) to recover transactions the bank never pushed", "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementImport" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementImportRequest" } } } }, "operationId": "postPaymentsStatements" } }, "/payments/statements/{id}": { "get": { "tags": [ "Transactions" ], "summary": "Statement import progress", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementImport" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Import id" } ], "operationId": "getPaymentsStatementsById" } }, "/payments/transactions/{id}/invoice-exempt": { "post": { "tags": [ "Transactions" ], "summary": "Mark money in as needing no invoice (left out of invoice reconciliation)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Transaction id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceExemptRequest" } } } }, "operationId": "postPaymentsTransactionsByIdInvoiceExempt" }, "delete": { "tags": [ "Transactions" ], "summary": "Put the transaction back into invoice reconciliation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Transaction id" } ], "operationId": "deletePaymentsTransactionsByIdInvoiceExempt" } }, "/einvoices/reconciliation": { "get": { "tags": [ "E-invoices" ], "summary": "Money in against invoices: what has one, what is missing one, what needs none, per day", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceReconciliation" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "First day (Vietnam time); default 29 days before `to`" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Last day, inclusive; default today" } ], "operationId": "getEinvoicesReconciliation" } }, "/einvoices/providers": { "get": { "tags": [ "E-invoices" ], "summary": "Providers you can connect, with the fields each needs", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EinvoiceProvider" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getEinvoicesProviders" } }, "/einvoices/connections/check": { "post": { "tags": [ "E-invoices" ], "summary": "Check provider credentials and list the account's templates (nothing is saved)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EinvoiceConnectionCheck" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckEinvoiceConnectionRequest" } } } }, "operationId": "postEinvoicesConnectionsCheck" } }, "/einvoices/connections": { "get": { "tags": [ "E-invoices" ], "summary": "List e-invoice provider connections", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EinvoiceConnection" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getEinvoicesConnections" }, "post": { "tags": [ "E-invoices" ], "summary": "Connect an e-invoice provider account (credentials and template are checked)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EinvoiceConnection" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEinvoiceConnectionRequest" } } } }, "operationId": "postEinvoicesConnections" } }, "/einvoices/connections/{id}": { "get": { "tags": [ "E-invoices" ], "summary": "Retrieve a provider connection", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EinvoiceConnection" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "operationId": "getEinvoicesConnectionsById" }, "delete": { "tags": [ "E-invoices" ], "summary": "Unlink a provider (its invoices are kept; the next provider becomes the default)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EinvoiceConnection" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "operationId": "deleteEinvoicesConnectionsById" }, "patch": { "tags": [ "E-invoices" ], "summary": "Change default mode, template, credentials or make it the default", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EinvoiceConnection" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEinvoiceConnectionRequest" } } } }, "operationId": "patchEinvoicesConnectionsById" } }, "/einvoices/connections/{id}/default": { "post": { "tags": [ "E-invoices" ], "summary": "Make this the default provider", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EinvoiceConnection" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "operationId": "postEinvoicesConnectionsByIdDefault" } }, "/einvoices/connections/{id}/templates": { "get": { "tags": [ "E-invoices" ], "summary": "Templates this provider account may issue on", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EinvoiceTemplate" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "operationId": "getEinvoicesConnectionsByIdTemplates" } }, "/einvoices/connections/{id}/sync": { "post": { "tags": [ "E-invoices" ], "summary": "Check every draft and unsettled invoice of this connection at the provider now", "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EinvoiceSync" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id" } ], "operationId": "postEinvoicesConnectionsByIdSync" } }, "/einvoices": { "post": { "tags": [ "E-invoices" ], "summary": "Create an invoice: the draft is created first, then (mode publish) sent for approval", "responses": { "201": { "description": "Created; sent to the provider in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Einvoice" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEinvoiceRequest" } } } }, "operationId": "postEinvoices" }, "get": { "tags": [ "E-invoices" ], "summary": "List invoices", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Einvoice" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated statuses" }, { "name": "payment_id", "in": "query", "schema": { "type": "string" } }, { "name": "sync_state", "in": "query", "schema": { "type": "string", "enum": [ "in_sync", "pending_push", "conflict" ] } } ], "operationId": "getEinvoices" } }, "/einvoices/{id}": { "get": { "tags": [ "E-invoices" ], "summary": "Retrieve an invoice", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Einvoice" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id" } ], "operationId": "getEinvoicesById" }, "patch": { "tags": [ "E-invoices" ], "summary": "Edit a draft", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Einvoice" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEinvoiceRequest" } } } }, "operationId": "patchEinvoicesById" }, "delete": { "tags": [ "E-invoices" ], "summary": "Delete a draft", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Einvoice" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id" } ], "operationId": "deleteEinvoicesById" } }, "/einvoices/{id}/publish": { "post": { "tags": [ "E-invoices" ], "summary": "Send a draft for approval (sign and issue it)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Einvoice" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id" } ], "operationId": "postEinvoicesByIdPublish" } }, "/einvoices/{id}/retry": { "post": { "tags": [ "E-invoices" ], "summary": "Run the failed step again", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Einvoice" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id" } ], "operationId": "postEinvoicesByIdRetry" } }, "/einvoices/{id}/replace": { "post": { "tags": [ "E-invoices" ], "summary": "Issue a replacement invoice", "responses": { "201": { "description": "The replacement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Einvoice" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceEinvoiceRequest" } } } }, "operationId": "postEinvoicesByIdReplace" } }, "/einvoices/{id}/resolve": { "post": { "tags": [ "E-invoices" ], "summary": "Settle a conflict: keep your draft or the provider's", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Einvoice" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveConflictRequest" } } } }, "operationId": "postEinvoicesByIdResolve" } }, "/einvoices/{id}/sync": { "post": { "tags": [ "E-invoices" ], "summary": "Check this invoice at the provider now", "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EinvoiceSync" } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id" } ], "operationId": "postEinvoicesByIdSync" } }, "/einvoices/{id}/history": { "get": { "tags": [ "E-invoices" ], "summary": "Status history (who changed what, on which side)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EinvoiceHistoryEntry" } } }, "required": [ "object", "data" ] } } } }, "401": { "description": "Missing API key or key lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid API key, unverified domain, or sending paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit (20 requests per second for this API) or daily quota exceeded; see the `retry-after` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id" } ], "operationId": "getEinvoicesByIdHistory" } }, "/pay/{id}": { "get": { "tags": [ "Checkout" ], "summary": "What the hosted checkout page shows", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkout" } } } }, "404": { "description": "Unknown payment" } }, "operationId": "getPayById" } }, "/pay/{id}/qr.svg": { "get": { "tags": [ "Checkout" ], "summary": "VietQR image, with the hatang mark in the middle unless `logo=0`", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment id" }, { "name": "logo", "in": "query", "description": "`0` leaves the mark out", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "1" } } ], "responses": { "200": { "description": "SVG", "content": { "image/svg+xml": { "schema": { "type": "string" } } } } }, "operationId": "getPayByIdQr.svg" } }, "/pay/{id}/events": { "get": { "tags": [ "Checkout" ], "summary": "Server-sent events with the payment status", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment id" } ], "responses": { "200": { "description": "text/event-stream" } }, "operationId": "getPayByIdEvents" } }, "/integrations/{provider}/{action}": { "get": { "tags": [ "Integrations" ], "summary": "Provider callback (verification)", "security": [], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Provider id, e.g. mbbank" }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string" }, "description": "e.g. token, notify" } ], "responses": { "200": { "description": "Accepted" }, "401": { "description": "Rejected" }, "404": { "description": "Unknown provider or action" } }, "operationId": "getIntegrationsByProviderByAction" }, "post": { "tags": [ "Integrations" ], "summary": "Provider callback: MB Bank token (API 32) and balance change (API 90); e-invoice status changes", "security": [], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Provider id, e.g. mbbank" }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string" }, "description": "e.g. token, notify" } ], "responses": { "200": { "description": "Stored" }, "401": { "description": "Rejected" }, "404": { "description": "Unknown provider or action" } }, "operationId": "postIntegrationsByProviderByAction" } }, "/stores/apple/{appId}": { "post": { "tags": [ "Tracking" ], "summary": "App Store Server Notifications v2 for one connected app (Apple-signed JWS in signedPayload)", "security": [], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site app id" } ], "responses": { "200": { "description": "Recorded, or a test notification" }, "400": { "description": "Not signed by Apple, or another bundle id" }, "404": { "description": "No App Store connection" } }, "operationId": "postStoresAppleByAppId" } }, "/stores/google/{appId}": { "post": { "tags": [ "Tracking" ], "summary": "Google Play real-time developer notifications (Pub/Sub push) for one connected app", "security": [], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site app id" }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The secret shown when connecting Google Play" } ], "responses": { "200": { "description": "Recorded, or a test notification" }, "403": { "description": "Wrong token" }, "404": { "description": "No Google Play connection" } }, "operationId": "postStoresGoogleByAppId" } }, "/channels/{channel}/webhook": { "get": { "tags": [ "Tracking" ], "summary": "Channel webhook verification (Zalo, Messenger)", "security": [], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel name" } ], "responses": { "200": { "description": "Challenge echoed" }, "404": { "description": "Unknown channel" } }, "operationId": "getChannelsByChannelWebhook" }, "post": { "tags": [ "Tracking" ], "summary": "Channel webhook receiver", "security": [], "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Channel name" } ], "responses": { "200": { "description": "Accepted" }, "404": { "description": "Unknown channel" } }, "operationId": "postChannelsByChannelWebhook" } }, "/o/{token}": { "get": { "tags": [ "Tracking" ], "summary": "Open-tracking pixel", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Signed token" } ], "responses": { "200": { "description": "1x1 GIF" } }, "operationId": "getOByToken" } }, "/c/{token}": { "get": { "tags": [ "Tracking" ], "summary": "Click redirect", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Signed token" } ], "responses": { "302": { "description": "Redirect to the original link" }, "400": { "description": "Invalid token" } }, "operationId": "getCByToken" } }, "/internal/tls-ask": { "get": { "tags": [ "Tracking" ], "summary": "On-demand TLS check used by the reverse proxy", "security": [], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Host is a configured tracking subdomain" }, "404": { "description": "Unknown host" } }, "operationId": "getInternalTlsAsk" } }, "/ses/events": { "post": { "tags": [ "Tracking" ], "summary": "Amazon SNS endpoint for SES delivery, bounce and complaint events (SES mode only)", "security": [], "responses": { "200": { "description": "Processed" }, "400": { "description": "Rejected (bad signature or payload)" } }, "operationId": "postSesEvents" } }, "/files/received/{attachment_id}": { "get": { "tags": [ "Receiving" ], "summary": "Download a received attachment (the signed download_url; no API key)", "security": [], "parameters": [ { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "exp", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "sig", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file" }, "404": { "description": "Link expired or invalid" } }, "operationId": "getFilesReceivedByAttachment_id" } }, "/ses/inbound": { "post": { "tags": [ "Tracking" ], "summary": "Amazon SNS endpoint for mail SES received for the chat inbox domain (stored in S3)", "security": [], "responses": { "200": { "description": "Processed or dropped" }, "400": { "description": "Rejected (bad signature, topic or payload)" }, "500": { "description": "Could not read or stage the message; SNS retries" } }, "operationId": "postSesInbound" } }, "/u/{token}": { "get": { "tags": [ "Tracking" ], "summary": "Email preferences page (topics, unsubscribe from all); opening it changes nothing", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact unsubscribe token" }, { "name": "topic", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Preferences page" }, "404": { "description": "Unknown token" } }, "operationId": "getUByToken" }, "post": { "tags": [ "Tracking" ], "summary": "One-click unsubscribe (RFC 8058): from the topic in the link, else from everything", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact unsubscribe token" }, { "name": "topic", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Unsubscribed" }, "404": { "description": "Unknown token" } }, "operationId": "postUByToken" } }, "/u/{token}/preferences": { "post": { "tags": [ "Tracking" ], "summary": "Save the preferences page form", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact unsubscribe token" } ], "responses": { "200": { "description": "Preferences page with a confirmation" }, "404": { "description": "Unknown token" } }, "operationId": "postUByTokenPreferences" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ht_...", "description": "API key with scopes such as `email:send`, `email:*`, `chat:*` or `*`. A key belongs to one business and works for every service its scopes cover." } }, "schemas": { "Error": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "name": { "type": "string", "enum": [ "validation_error", "missing_required_field", "missing_api_key", "invalid_api_key", "restricted_api_key", "invalid_from_address", "not_found", "method_not_allowed", "invalid_idempotent_request", "concurrent_idempotent_requests", "rate_limit_exceeded", "daily_quota_exceeded", "invalid_attachment", "application_error", "internal_server_error", "origin_not_allowed", "invalid_visitor_token", "invalid_agent_token", "site_disabled", "invalid_app_key", "app_key_revoked", "message_too_long", "unsupported_file_type", "file_too_large", "conversation_closed", "product_not_enabled", "product_disabled", "ai_budget_exhausted", "ai_not_configured", "ai_unavailable", "instructions_full", "forbidden", "last_owner", "domain_taken", "host_missing", "host_mismatch", "slug_taken", "slug_reserved", "environment_mismatch", "no_bank_connection", "code_taken", "bank_link_failed", "invalid_otp", "otp_expired", "invalid_state", "provider_unavailable", "invoice_provider_error" ] }, "message": { "type": "string" } }, "required": [ "statusCode", "name", "message" ] }, "Tag": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] }, "SendEmailRequest": { "type": "object", "properties": { "from": { "description": "Required unless the template sets one", "type": "string", "minLength": 3, "maxLength": 320 }, "to": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 320 } } ] }, "cc": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 320 } } ] }, "bcc": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 320 } } ] }, "reply_to": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 320 } } ] }, "subject": { "default": "", "type": "string", "maxLength": 998 }, "html": { "type": "string", "maxLength": 10000000 }, "text": { "type": "string", "maxLength": 10000000 }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "tags": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "name", "value" ] } }, "attachments": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "anyOf": [ { "type": "string" }, {} ] }, "path": { "type": "string", "format": "uri" }, "content_type": { "type": "string" }, "content_id": { "type": "string" } }, "required": [ "filename" ] } }, "scheduled_at": { "type": "string" }, "template": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Template id (tpl_…) or alias; only published templates can be sent" }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } } }, "required": [ "id" ] }, "topic_id": { "description": "Skip recipients who opted out of this topic (contacts not in the list follow the topic default)", "type": "string" } }, "required": [ "to" ] }, "BatchSendRequest": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "from": { "description": "Required unless the template sets one", "type": "string", "minLength": 3, "maxLength": 320 }, "to": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 320 } } ] }, "cc": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 320 } } ] }, "bcc": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 320 } } ] }, "reply_to": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 320 } } ] }, "subject": { "default": "", "type": "string", "maxLength": 998 }, "html": { "type": "string", "maxLength": 10000000 }, "text": { "type": "string", "maxLength": 10000000 }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "tags": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "name", "value" ] } }, "attachments": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "anyOf": [ { "type": "string" }, {} ] }, "path": { "type": "string", "format": "uri" }, "content_type": { "type": "string" }, "content_id": { "type": "string" } }, "required": [ "filename" ] } }, "scheduled_at": { "type": "string" }, "template": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Template id (tpl_…) or alias; only published templates can be sent" }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } } }, "required": [ "id" ] }, "topic_id": { "description": "Skip recipients who opted out of this topic (contacts not in the list follow the topic default)", "type": "string" } }, "required": [ "to" ] } }, "UpdateEmailRequest": { "type": "object", "properties": { "scheduled_at": { "type": "string" } }, "required": [ "scheduled_at" ] }, "Email": { "type": "object", "properties": { "object": { "type": "string", "const": "email" }, "id": { "type": "string", "format": "uuid" }, "to": { "type": "array", "items": { "type": "string" } }, "from": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "subject": { "type": "string" }, "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "bcc": { "type": [ "array", "null" ], "items": { "type": "string" } }, "cc": { "type": [ "array", "null" ], "items": { "type": "string" } }, "reply_to": { "type": [ "array", "null" ], "items": { "type": "string" } }, "last_event": { "type": "string", "enum": [ "queued", "sent", "delivered", "delivery_delayed", "bounced", "complained", "opened", "clicked", "failed" ] }, "status": { "type": "string", "enum": [ "queued", "scheduled", "sent", "delivered", "delivery_delayed", "bounced", "complained", "canceled", "failed" ] }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "object", "id", "to", "from", "created_at", "subject", "html", "text", "bcc", "cc", "reply_to", "last_event", "status", "scheduled_at", "tags", "headers" ] }, "EmailEvents": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object" } }, "required": [ "id", "type", "created_at", "data" ] } }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "kind": { "type": "string", "enum": [ "to", "cc", "bcc" ] }, "status": { "type": "string", "enum": [ "pending", "sent", "delivered", "delayed", "bounced", "suppressed", "canceled" ] }, "attempts": { "type": "integer" }, "last_smtp_code": { "type": [ "integer", "null" ] }, "last_smtp_response": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "address", "kind", "status", "attempts", "last_smtp_code", "last_smtp_response", "next_attempt_at" ] } } }, "required": [ "object", "data", "recipients" ] }, "CreateDomainRequest": { "type": "object", "properties": { "website_id": { "description": "Deprecated: websites are gone. Optional legacy organization id; the business's own record is used when omitted.", "type": "string" }, "name": { "type": "string", "minLength": 3, "maxLength": 253 }, "region": { "description": "Optional. Stored for compatibility; sending uses the platform SES region.", "type": "string", "enum": [ "us-east-1", "us-west-2", "eu-west-1", "sa-east-1", "ap-northeast-1", "ap-southeast-1" ] }, "custom_return_path": { "default": "send", "description": "Subdomain used for the bounce address and SPF alignment, e.g. `send` → send.example.com", "type": "string", "pattern": "^[a-z0-9-]{1,63}$" }, "tracking_subdomain": { "description": "Subdomain to CNAME at the platform so tracked links use your domain, e.g. `links` → links.example.com", "type": "string", "pattern": "^[a-z0-9-]{1,63}$" }, "open_tracking": { "default": false, "type": "boolean" }, "click_tracking": { "default": false, "type": "boolean" } }, "required": [ "name" ] }, "UpdateDomainRequest": { "type": "object", "properties": { "open_tracking": { "type": "boolean" }, "click_tracking": { "type": "boolean" }, "tls": { "type": "string", "enum": [ "opportunistic", "enforced" ] }, "tracking_subdomain": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9-]{1,63}$" }, { "type": "null" } ] }, "capabilities": { "type": "object", "properties": { "receiving": { "description": "Receive mail on this domain: publish the RECEIVING MX record, then every message fires email.received", "type": "string", "enum": [ "enabled", "disabled" ] } } } } }, "DomainRecord": { "type": "object", "properties": { "record": { "type": "string", "enum": [ "MX", "SPF", "DKIM", "DMARC", "TRACKING", "RECEIVING" ] }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "TXT", "MX", "CNAME" ] }, "ttl": { "type": "string" }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "failed" ] }, "value": { "type": "string" }, "priority": { "type": "integer" }, "required": { "type": "boolean" }, "last_error": { "type": "string" } }, "required": [ "record", "name", "type", "ttl", "status", "value", "required" ] }, "Domain": { "type": "object", "properties": { "object": { "type": "string", "const": "domain" }, "id": { "type": "string" }, "website_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified", "failed", "temporary_failure" ] }, "created_at": { "type": "string", "format": "date-time" }, "region": { "type": "string" }, "dkim_selector": { "type": "string" }, "open_tracking": { "type": "boolean" }, "click_tracking": { "type": "boolean" }, "tracking_subdomain": { "type": [ "string", "null" ] }, "tracking_domain_verified": { "type": "boolean" }, "custom_return_path": { "type": "string" }, "tls": { "type": "string", "enum": [ "opportunistic", "enforced" ] }, "capabilities": { "type": "object", "properties": { "sending": { "type": "string", "enum": [ "enabled" ] }, "receiving": { "type": "string", "enum": [ "enabled", "disabled" ] } }, "required": [ "sending", "receiving" ] }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DomainRecord" } } }, "required": [ "object", "id", "website_id", "name", "status", "created_at", "region", "dkim_selector", "open_tracking", "click_tracking", "tracking_subdomain", "tracking_domain_verified", "custom_return_path", "tls", "capabilities", "records" ] }, "ReceivedAttachmentMeta": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "content_disposition": { "type": "string", "enum": [ "inline", "attachment" ] }, "content_id": { "type": [ "string", "null" ] }, "size": { "type": "integer" } }, "required": [ "id", "filename", "content_type", "content_disposition", "content_id", "size" ] }, "ReceivedAttachment": { "type": "object", "properties": { "object": { "type": "string", "const": "attachment" }, "id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "content_disposition": { "type": "string", "enum": [ "inline", "attachment" ] }, "content_id": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "download_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "filename", "content_type", "content_disposition", "content_id", "size", "download_url", "expires_at" ] }, "ReceivedEmailSummary": { "type": "object", "properties": { "object": { "type": "string", "const": "email" }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "message_id": { "type": [ "string", "null" ] }, "subject": { "type": "string" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedAttachmentMeta" } } }, "required": [ "object", "id", "created_at", "from", "to", "cc", "bcc", "message_id", "subject", "attachments" ] }, "ReceivedEmail": { "type": "object", "properties": { "object": { "type": "string", "const": "email" }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "reply_to": { "type": "array", "items": { "type": "string" } }, "message_id": { "type": [ "string", "null" ] }, "in_reply_to": { "type": [ "string", "null" ] }, "subject": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "html": { "type": [ "string", "null" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "spam": { "type": "boolean" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedAttachmentMeta" } } }, "required": [ "object", "id", "created_at", "from", "to", "cc", "bcc", "reply_to", "message_id", "in_reply_to", "subject", "text", "html", "headers", "spam", "attachments" ] }, "CreateApiKeyRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "permission": { "type": "string", "enum": [ "full_access", "sending_access" ] }, "scopes": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "enum": [ "*", "email:*", "email:read", "email:write", "email:send", "chat:*", "chat:read", "chat:write", "chat:send", "payments:*", "payments:read", "payments:write", "payments:send", "blog:*", "blog:read", "blog:write", "blog:send", "products:*", "products:read", "products:write", "products:send", "crm:*", "crm:read", "crm:write", "crm:send", "accounting:*", "accounting:read", "accounting:write", "accounting:send" ] } }, "domain_id": { "type": "string" } }, "required": [ "name" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "permission": { "type": "string", "enum": [ "full_access", "sending_access", "custom" ], "description": "Legacy permission field derived from scopes" }, "scopes": { "type": "array", "items": { "type": "string" } }, "token_prefix": { "type": "string" } }, "required": [ "id", "name", "created_at", "permission", "scopes", "token_prefix" ] }, "CreateWebhookRequest": { "type": "object", "properties": { "endpoint": { "type": "string", "format": "uri" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.opened", "email.clicked", "email.failed", "email.received", "contact.created", "contact.updated", "contact.deleted", "domain.created", "domain.updated", "domain.deleted", "chat.conversation.created", "chat.conversation.assigned", "chat.conversation.resolved", "chat.conversation.closed", "chat.conversation.reopened", "chat.conversation.handoff", "chat.conversation.tagged", "chat.message.created", "chat.visitor.identified", "chat.order.created", "chat.order.updated", "chat.order.paid", "chat.flow.webhook", "chat.campaign.lead", "chat.ticket.created", "chat.ticket.updated", "chat.ticket.resolved", "chat.ticket.breached", "chat.rating.created", "chat.zns.sent", "chat.zns.failed", "payment.created", "payment.succeeded", "payment.partially_paid", "payment.overpaid", "payment.expired", "payment.canceled", "transaction.received", "bank_connection.activated", "bank_connection.revoked", "bank_connection.needs_reauth", "invoice.draft_created", "invoice.draft_updated", "invoice.draft_deleted", "invoice.issued", "invoice.tax_accepted", "invoice.tax_rejected", "invoice.canceled", "invoice.replaced", "invoice.adjusted", "invoice.failed", "invoice.conflict" ] } }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "endpoint", "events" ] }, "UpdateWebhookRequest": { "type": "object", "properties": { "endpoint": { "type": "string", "format": "uri" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.opened", "email.clicked", "email.failed", "email.received", "contact.created", "contact.updated", "contact.deleted", "domain.created", "domain.updated", "domain.deleted", "chat.conversation.created", "chat.conversation.assigned", "chat.conversation.resolved", "chat.conversation.closed", "chat.conversation.reopened", "chat.conversation.handoff", "chat.conversation.tagged", "chat.message.created", "chat.visitor.identified", "chat.order.created", "chat.order.updated", "chat.order.paid", "chat.flow.webhook", "chat.campaign.lead", "chat.ticket.created", "chat.ticket.updated", "chat.ticket.resolved", "chat.ticket.breached", "chat.rating.created", "chat.zns.sent", "chat.zns.failed", "payment.created", "payment.succeeded", "payment.partially_paid", "payment.overpaid", "payment.expired", "payment.canceled", "transaction.received", "bank_connection.activated", "bank_connection.revoked", "bank_connection.needs_reauth", "invoice.draft_created", "invoice.draft_updated", "invoice.draft_deleted", "invoice.issued", "invoice.tax_accepted", "invoice.tax_rejected", "invoice.canceled", "invoice.replaced", "invoice.adjusted", "invoice.failed", "invoice.conflict" ] } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "description": { "type": "string", "maxLength": 500 } } }, "Webhook": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook" }, "id": { "type": "string" }, "endpoint": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "signing_secret": { "type": "string", "description": "Only returned on creation. Verify payloads with the svix library." } }, "required": [ "object", "id", "endpoint", "events", "status", "created_at" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "svix_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed", "exhausted" ] }, "attempt": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ] }, "response_ms": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object" } }, "required": [ "id", "svix_id", "event_type", "status", "attempt", "response_status", "response_ms", "last_error", "next_attempt_at", "delivered_at", "created_at", "payload" ] }, "CreateAudienceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] }, "Audience": { "type": "object", "properties": { "object": { "type": "string", "const": "audience" }, "id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "contact_count": { "type": "integer" } }, "required": [ "object", "id", "name", "created_at" ] }, "CreateContactRequest": { "type": "object", "properties": { "email": { "type": "string", "minLength": 3, "maxLength": 320 }, "first_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "unsubscribed": { "description": "Unsubscribed from everything", "type": "boolean" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number" }, { "type": "null" } ] }, "description": "Values of declared contact properties; null removes one" }, "segments": { "description": "Add to these segments", "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "topics": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ] } }, "required": [ "id", "subscription" ] } } }, "required": [ "email" ] }, "UpdateContactRequest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "unsubscribed": { "type": "boolean" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number" }, { "type": "null" } ] }, "description": "Values of declared contact properties; null removes one" } } }, "Contact": { "type": "object", "properties": { "object": { "type": "string", "const": "contact" }, "id": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "unsubscribed": { "type": "boolean" }, "properties": { "type": "object", "additionalProperties": { "type": [ "string", "number" ] } } }, "required": [ "object", "id", "email", "first_name", "last_name", "created_at", "unsubscribed", "properties" ] }, "CreateBroadcastRequest": { "type": "object", "properties": { "segment_id": { "description": "Segment to send to (audience_id is the older name)", "type": "string" }, "audience_id": { "type": "string" }, "topic_id": { "description": "Only contacts subscribed to this topic", "type": [ "string", "null" ] }, "template_id": { "description": "Copy html, text, from and subject from this published template (fields you send win)", "type": "string" }, "from": { "description": "Required unless template_id supplies it", "type": "string", "minLength": 3, "maxLength": 320 }, "subject": { "description": "Required unless template_id supplies it", "type": "string", "minLength": 1, "maxLength": 998 }, "reply_to": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 320 } } ] }, "html": { "type": "string" }, "text": { "type": "string" }, "name": { "type": "string", "maxLength": 200 } } }, "UpdateBroadcastRequest": { "type": "object", "properties": { "segment_id": { "description": "Segment to send to (audience_id is the older name)", "type": "string" }, "audience_id": { "type": "string" }, "topic_id": { "description": "Only contacts subscribed to this topic", "type": [ "string", "null" ] }, "template_id": { "description": "Copy html, text, from and subject from this published template (fields you send win)", "type": "string" }, "from": { "description": "Required unless template_id supplies it", "type": "string", "minLength": 3, "maxLength": 320 }, "subject": { "description": "Required unless template_id supplies it", "type": "string", "minLength": 1, "maxLength": 998 }, "reply_to": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 320 } } ] }, "html": { "type": "string" }, "text": { "type": "string" }, "name": { "type": "string", "maxLength": 200 } } }, "SendBroadcastRequest": { "type": "object", "properties": { "scheduled_at": { "type": "string" } } }, "EmailMetrics": { "type": "object", "properties": { "object": { "type": "string", "const": "metrics" }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "granularity": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "dimensions": { "type": "array", "items": { "type": "string" } }, "totals": { "type": "object", "additionalProperties": { "type": "number" } }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "period, domain_id/domain_name when split by domain, then one key per metric" } } }, "required": [ "object", "start_date", "end_date", "timezone", "granularity", "metrics", "dimensions", "totals", "data" ] }, "RequestLog": { "type": "object", "properties": { "object": { "type": "string", "const": "log" }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "endpoint": { "type": "string" }, "method": { "type": "string" }, "response_status": { "type": "integer" }, "duration_ms": { "type": "integer" }, "user_agent": { "type": [ "string", "null" ] }, "sdk": { "type": [ "string", "null" ] }, "api_key_id": { "type": [ "string", "null" ] } }, "required": [ "object", "id", "created_at", "endpoint", "method", "response_status", "duration_ms", "user_agent", "sdk", "api_key_id" ] }, "RequestLogDetail": { "type": "object", "properties": { "object": { "type": "string", "const": "log" }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "endpoint": { "type": "string" }, "method": { "type": "string" }, "response_status": { "type": "integer" }, "duration_ms": { "type": "integer" }, "user_agent": { "type": [ "string", "null" ] }, "sdk": { "type": [ "string", "null" ] }, "api_key_id": { "type": [ "string", "null" ] }, "request_body": { "description": "JSON body as sent, secrets redacted" }, "response_body": { "description": "JSON body as returned" }, "resource_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "object", "id", "created_at", "endpoint", "method", "response_status", "duration_ms", "user_agent", "sdk", "api_key_id", "request_body", "response_body", "resource_ids" ] }, "Usage": { "type": "object", "properties": { "object": { "type": "string", "const": "usage" }, "emails": { "type": "object", "additionalProperties": true }, "domains": { "type": "object", "additionalProperties": true }, "contacts": { "type": "object", "additionalProperties": true }, "templates": { "type": "object", "additionalProperties": true }, "automation_runs": { "type": "object", "additionalProperties": true } }, "required": [ "object", "emails", "domains", "contacts", "templates", "automation_runs" ] }, "CreateSegmentRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] }, "Segment": { "type": "object", "properties": { "object": { "type": "string", "const": "segment" }, "id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "contact_count": { "type": "integer" } }, "required": [ "object", "id", "name", "created_at", "contact_count" ] }, "CreateTopicRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "default_subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ], "description": "Fixed once created" }, "visibility": { "default": "private", "type": "string", "enum": [ "public", "private" ] } }, "required": [ "name", "default_subscription" ] }, "UpdateTopicRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "private" ] } } }, "Topic": { "type": "object", "properties": { "object": { "type": "string", "const": "topic" }, "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "default_subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ] }, "visibility": { "type": "string", "enum": [ "public", "private" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "description", "default_subscription", "visibility", "created_at" ] }, "ContactTopic": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ] } }, "required": [ "id", "name", "description", "subscription" ] }, "UpdateContactTopicsRequest": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "subscription": { "type": "string", "enum": [ "opt_in", "opt_out" ] } }, "required": [ "id", "subscription" ] } }, "CreateContactPropertyRequest": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,50}$" }, "type": { "default": "string", "type": "string", "enum": [ "string", "number" ] }, "fallback_value": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number" }, { "type": "null" } ] } }, "required": [ "key" ] }, "UpdateContactPropertyRequest": { "type": "object", "properties": { "fallback_value": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number" }, { "type": "null" } ] } }, "required": [ "fallback_value" ] }, "ContactProperty": { "type": "object", "properties": { "object": { "type": "string", "const": "contact_property" }, "id": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number" ] }, "fallback_value": { "type": [ "string", "number", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "key", "type", "fallback_value", "created_at" ] }, "CreateEventRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] } } }, "required": [ "name" ] }, "UpdateEventRequest": { "type": "object", "properties": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] } } }, "required": [ "schema" ] }, "SendEventRequest": { "type": "object", "properties": { "event": { "type": "string", "minLength": 1, "maxLength": 100 }, "contact_id": { "type": "string" }, "email": { "description": "Creates the contact when it does not exist", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "event" ] }, "EventDef": { "type": "object", "properties": { "object": { "type": "string", "const": "event" }, "id": { "type": "string" }, "name": { "type": "string" }, "schema": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] } }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "schema", "created_at" ] }, "CreateAutomationRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "steps": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "trigger", "send_email", "delay", "wait_for_event", "condition", "update_contact", "add_to_segment" ] }, "config": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "key", "type" ] } }, "connections": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "default", "condition_met", "condition_not_met", "event_received", "timeout" ] } }, "required": [ "from", "to" ] } } }, "required": [ "name" ] }, "UpdateAutomationRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "steps": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "trigger", "send_email", "delay", "wait_for_event", "condition", "update_contact", "add_to_segment" ] }, "config": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "key", "type" ] } }, "connections": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string", "enum": [ "default", "condition_met", "condition_not_met", "event_received", "timeout" ] } }, "required": [ "from", "to" ] } } } }, "Automation": { "type": "object", "properties": { "object": { "type": "string", "const": "automation" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "config": { "type": "object", "additionalProperties": true } } } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string" } } } }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "status", "steps", "connections", "version", "created_at", "updated_at" ] }, "AutomationRun": { "type": "object", "properties": { "object": { "type": "string", "const": "automation_run" }, "id": { "type": "string" }, "automation_id": { "type": "string" }, "version": { "type": "integer" }, "contact_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "running", "waiting", "completed", "failed", "cancelled", "skipped" ] }, "current_step": { "type": [ "string", "null" ] }, "waiting_for": { "type": [ "string", "null" ] }, "wait_until": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "steps": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "object", "id", "automation_id", "version", "contact_id", "status", "current_step", "waiting_for", "wait_until", "error", "started_at", "completed_at", "steps" ] }, "CreateTemplateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "html": { "type": "string", "maxLength": 10000000 }, "alias": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "from": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "type": "null" } ] }, "subject": { "anyOf": [ { "type": "string", "maxLength": 998 }, { "type": "null" } ] }, "reply_to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "text": { "description": "Generated from html when omitted", "anyOf": [ { "type": "string", "maxLength": 10000000 }, { "type": "null" } ] }, "variables": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,50}$" }, "type": { "default": "string", "type": "string", "enum": [ "string", "number" ] }, "fallback_value": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number" }, { "type": "null" } ] } }, "required": [ "key" ] } }, "folder": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "name", "html" ] }, "UpdateTemplateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "html": { "type": "string", "maxLength": 10000000 }, "alias": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "from": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 320 }, { "type": "null" } ] }, "subject": { "anyOf": [ { "type": "string", "maxLength": 998 }, { "type": "null" } ] }, "reply_to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "text": { "description": "Generated from html when omitted", "anyOf": [ { "type": "string", "maxLength": 10000000 }, { "type": "null" } ] }, "variables": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,50}$" }, "type": { "default": "string", "type": "string", "enum": [ "string", "number" ] }, "fallback_value": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number" }, { "type": "null" } ] } }, "required": [ "key" ] } }, "folder": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } } }, "TemplateVariable": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number" ] }, "fallback_value": { "type": [ "string", "number", "null" ] } }, "required": [ "key", "type", "fallback_value" ] }, "TemplateSummary": { "type": "object", "properties": { "object": { "type": "string", "const": "template" }, "id": { "type": "string" }, "current_version_id": { "type": [ "string", "null" ] }, "alias": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_unpublished_versions": { "type": "boolean" }, "from": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "reply_to": { "type": "array", "items": { "type": "string" } }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" } }, "folder": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "current_version_id", "alias", "name", "status", "published_at", "has_unpublished_versions", "from", "subject", "reply_to", "variables", "folder", "created_at", "updated_at" ] }, "Template": { "type": "object", "properties": { "object": { "type": "string", "const": "template" }, "id": { "type": "string" }, "current_version_id": { "type": [ "string", "null" ] }, "alias": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_unpublished_versions": { "type": "boolean" }, "from": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "reply_to": { "type": "array", "items": { "type": "string" } }, "html": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" } }, "folder": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "current_version_id", "alias", "name", "status", "published_at", "has_unpublished_versions", "from", "subject", "reply_to", "html", "text", "variables", "folder", "created_at", "updated_at" ] }, "Broadcast": { "type": "object", "properties": { "object": { "type": "string", "const": "broadcast" }, "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "audience_id": { "type": "string" }, "from": { "type": "string" }, "subject": { "type": "string" }, "reply_to": { "type": [ "array", "null" ], "items": { "type": "string" } }, "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "queued", "sending", "sent", "canceled" ] }, "created_at": { "type": "string", "format": "date-time" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "total": { "type": "integer" }, "sent_count": { "type": "integer" } }, "required": [ "object", "id", "name", "audience_id", "from", "subject", "reply_to", "html", "text", "status", "created_at", "scheduled_at", "sent_at", "total", "sent_count" ] }, "ChatSiteRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "website_id": { "description": "Deprecated: websites are gone. Optional legacy organization id; the business's own record is used when omitted.", "type": "string" }, "domain": { "description": "Defaults to the domain's host. Otherwise a subdomain of it, e.g. shop.acme.vn.", "type": "string", "minLength": 3, "maxLength": 253 }, "allowed_origins": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uri" } }, "settings": { "type": "object", "properties": { "color": { "default": "#111111", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "position": { "default": "right", "type": "string", "enum": [ "right", "left" ] }, "launcher": { "default": {}, "type": "object", "properties": { "icon": { "default": "chat", "type": "string", "enum": [ "chat", "support", "help", "message" ] }, "image_url": { "default": null, "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "label": { "default": {}, "type": "object", "properties": { "vi": { "default": "", "type": "string", "maxLength": 24 }, "en": { "default": "", "type": "string", "maxLength": 24 } } } } }, "locale_default": { "default": "auto", "type": "string", "enum": [ "vi", "en", "auto" ] }, "greeting": { "default": {}, "type": "object", "properties": { "vi": { "default": "Xin chào! Chúng tôi có thể giúp gì cho bạn?", "type": "string", "maxLength": 300 }, "en": { "default": "Hi there! How can we help?", "type": "string", "maxLength": 300 } } }, "away_message": { "default": {}, "type": "object", "properties": { "vi": { "default": "Hiện chúng tôi đang vắng mặt. Để lại email, chúng tôi sẽ trả lời sớm.", "type": "string", "maxLength": 300 }, "en": { "default": "We're away right now. Leave your email and we'll reply soon.", "type": "string", "maxLength": 300 } } }, "office_hours": { "default": null, "anyOf": [ { "type": "object", "properties": { "tz": { "default": "Asia/Ho_Chi_Minh", "type": "string" }, "days": { "default": {}, "type": "object", "propertyNames": { "type": "string", "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ] }, "additionalProperties": { "maxItems": 4, "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } ], "items": false, "minItems": 2, "maxItems": 2 } } }, "holidays": { "default": [], "maxItems": 60, "type": "array", "items": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } } }, { "type": "null" } ] }, "offline_capture": { "default": "email_required", "type": "string", "enum": [ "email_required", "email_optional", "off" ] }, "hide_when_offline": { "default": false, "type": "boolean" }, "theme": { "default": "light", "type": "string", "enum": [ "light", "dark", "auto" ] }, "transcript_on_resolve": { "default": false, "type": "boolean" }, "bot_enabled": { "default": false, "type": "boolean" }, "notify_emails": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "allow_in_iframe": { "default": false, "type": "boolean" }, "email_from": { "default": null, "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "follow_up": { "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "mode": { "default": "fixed", "type": "string", "enum": [ "fixed", "ai" ] }, "after_minutes": { "default": 1440, "type": "integer", "minimum": 5, "maximum": 43200 }, "max": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "message": { "default": { "vi": "Mình vẫn ở đây nếu bạn cần hỗ trợ thêm nhé!", "en": "We're still here if you need anything else!" }, "type": "object", "properties": { "vi": { "default": "Mình vẫn ở đây nếu bạn cần hỗ trợ thêm nhé!", "type": "string", "maxLength": 1000 }, "en": { "default": "We're still here if you need anything else!", "type": "string", "maxLength": 1000 } } }, "ai_hint": { "default": "", "type": "string", "maxLength": 500 } } }, "social_proof": { "default": { "enabled": false, "source": "orders", "manual": [], "interval_seconds": 45, "max_per_session": 3 }, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "source": { "default": "orders", "type": "string", "enum": [ "orders", "manual" ] }, "manual": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "text": { "type": "string", "maxLength": 120 }, "city": { "type": "string", "maxLength": 60 } }, "required": [ "name", "text" ] } }, "interval_seconds": { "default": 45, "type": "integer", "minimum": 10, "maximum": 600 }, "max_per_session": { "default": 3, "type": "integer", "minimum": 1, "maximum": 20 } } }, "csat": { "default": { "enabled": false, "ask": { "vi": "Bạn đánh giá cuộc trò chuyện hôm nay thế nào?", "en": "How was your conversation today?" } }, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "ask": { "default": { "vi": "Bạn đánh giá cuộc trò chuyện hôm nay thế nào?", "en": "How was your conversation today?" }, "type": "object", "properties": { "vi": { "default": "Bạn đánh giá cuộc trò chuyện hôm nay thế nào?", "type": "string", "maxLength": 300 }, "en": { "default": "How was your conversation today?", "type": "string", "maxLength": 300 } } } } }, "conversion_tracking": { "default": { "enabled": false, "ga4_measurement_id": null, "ga4_api_secret": null, "meta_pixel_id": null, "meta_capi_token": null, "google_ads_conversion": null }, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "ga4_measurement_id": { "default": null, "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "ga4_api_secret": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "meta_pixel_id": { "default": null, "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "meta_capi_token": { "default": null, "anyOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ] }, "google_ads_conversion": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] } } }, "auto_resolve_days": { "default": 3, "type": "integer", "minimum": 0, "maximum": 365 }, "ai": { "default": {}, "type": "object", "properties": { "mode": { "default": "off", "type": "string", "enum": [ "off", "when_offline", "first_responder", "draft" ] }, "draft_after_handoff": { "default": true, "type": "boolean" }, "model": { "default": null, "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "persona_name": { "default": "Trợ lý", "type": "string", "maxLength": 60 }, "instructions": { "default": "", "type": "string", "maxLength": 4000 }, "handoff_phrase": { "default": {}, "type": "object", "properties": { "vi": { "default": "Mình sẽ chuyển bạn tới nhân viên hỗ trợ ngay nhé.", "type": "string", "maxLength": 300 }, "en": { "default": "Let me connect you with a human agent.", "type": "string", "maxLength": 300 } } }, "max_bot_turns": { "default": 6, "type": "integer", "minimum": 1, "maximum": 20 }, "collect_email": { "default": true, "type": "boolean" }, "collect_info": { "default": true, "type": "boolean" }, "situations": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_-]{1,32}$" }, "name": { "type": "string", "maxLength": 80 }, "enabled": { "default": true, "type": "boolean" }, "once": { "default": true, "type": "boolean" }, "when": { "default": "topic", "type": "string", "enum": [ "every_message", "keywords", "topic" ] }, "keywords": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "topic": { "default": "", "type": "string", "maxLength": 300 }, "office_hours": { "default": "any", "type": "string", "enum": [ "any", "within", "outside" ] }, "channels": { "default": [], "maxItems": 12, "type": "array", "items": { "type": "string", "enum": [ "web", "zalo", "messenger", "email", "instagram", "tiktokshop", "zalo_personal", "tiktok", "whatsapp", "telegram", "x", "line" ] } }, "site_ids": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "instructions": { "default": "", "type": "string", "maxLength": 1000 }, "context": { "default": "", "type": "string", "maxLength": 2000 }, "then": { "default": "none", "type": "string", "enum": [ "none", "handoff", "add_agent", "stop", "spam" ] }, "agent_ids": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "id", "name" ] } } } }, "header": { "default": {}, "type": "object", "properties": { "subtitle": { "default": {}, "type": "object", "properties": { "vi": { "default": "", "type": "string", "maxLength": 120 }, "en": { "default": "", "type": "string", "maxLength": 120 } } }, "logo_url": { "default": null, "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "profile": { "default": "agents", "type": "string", "enum": [ "agents", "agents_or_logo", "member", "business" ] }, "member_id": { "default": null, "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } } }, "greeting_options": { "default": {}, "type": "object", "properties": { "enabled": { "default": true, "type": "boolean" }, "on_mobile": { "default": true, "type": "boolean" }, "sender": { "default": "none", "type": "string", "enum": [ "none", "online_agent" ] }, "teaser_seconds": { "default": 0, "type": "integer", "minimum": 0, "maximum": 120 } } }, "contact": { "default": {}, "type": "object", "properties": { "zalo": { "default": false, "type": "boolean" }, "messenger": { "default": false, "type": "boolean" }, "phone": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\+?[0-9][0-9 .-]{5,19}$" }, { "type": "null" } ] }, "email": { "default": null, "anyOf": [ { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] } } }, "layout": { "default": {}, "type": "object", "properties": { "size": { "default": "m", "type": "string", "enum": [ "s", "m", "l" ] }, "offset": { "default": null, "anyOf": [ { "type": "object", "properties": { "bottom": { "type": "integer", "minimum": 0, "maximum": 400 }, "side": { "type": "integer", "minimum": 0, "maximum": 400 } }, "required": [ "bottom", "side" ] }, { "type": "null" } ] }, "mobile_offset": { "default": null, "anyOf": [ { "type": "object", "properties": { "bottom": { "type": "integer", "minimum": 0, "maximum": 400 }, "side": { "type": "integer", "minimum": 0, "maximum": 400 } }, "required": [ "bottom", "side" ] }, { "type": "null" } ] } } }, "prechat": { "default": {}, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "fields": { "default": {}, "type": "object", "properties": { "name": { "default": "optional", "type": "string", "enum": [ "off", "optional", "required" ] }, "phone": { "default": "required", "type": "string", "enum": [ "off", "optional", "required" ] }, "email": { "default": "off", "type": "string", "enum": [ "off", "optional", "required" ] } } } } }, "visibility": { "default": {}, "type": "object", "properties": { "devices": { "default": "all", "type": "string", "enum": [ "all", "desktop", "mobile" ] }, "url_include": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "url_exclude": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } } }, "notifications": { "default": {}, "type": "object", "properties": { "sound": { "default": true, "type": "boolean" }, "title_alert": { "default": true, "type": "boolean" } } } } } }, "required": [ "name" ] }, "ChatSiteUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "domain": { "type": "string", "minLength": 3, "maxLength": 253 }, "allowed_origins": { "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uri" } }, "settings": { "type": "object", "properties": { "color": { "default": "#111111", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "position": { "default": "right", "type": "string", "enum": [ "right", "left" ] }, "launcher": { "default": {}, "type": "object", "properties": { "icon": { "default": "chat", "type": "string", "enum": [ "chat", "support", "help", "message" ] }, "image_url": { "default": null, "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "label": { "default": {}, "type": "object", "properties": { "vi": { "default": "", "type": "string", "maxLength": 24 }, "en": { "default": "", "type": "string", "maxLength": 24 } } } } }, "locale_default": { "default": "auto", "type": "string", "enum": [ "vi", "en", "auto" ] }, "greeting": { "default": {}, "type": "object", "properties": { "vi": { "default": "Xin chào! Chúng tôi có thể giúp gì cho bạn?", "type": "string", "maxLength": 300 }, "en": { "default": "Hi there! How can we help?", "type": "string", "maxLength": 300 } } }, "away_message": { "default": {}, "type": "object", "properties": { "vi": { "default": "Hiện chúng tôi đang vắng mặt. Để lại email, chúng tôi sẽ trả lời sớm.", "type": "string", "maxLength": 300 }, "en": { "default": "We're away right now. Leave your email and we'll reply soon.", "type": "string", "maxLength": 300 } } }, "office_hours": { "default": null, "anyOf": [ { "type": "object", "properties": { "tz": { "default": "Asia/Ho_Chi_Minh", "type": "string" }, "days": { "default": {}, "type": "object", "propertyNames": { "type": "string", "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ] }, "additionalProperties": { "maxItems": 4, "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } ], "items": false, "minItems": 2, "maxItems": 2 } } }, "holidays": { "default": [], "maxItems": 60, "type": "array", "items": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } } }, { "type": "null" } ] }, "offline_capture": { "default": "email_required", "type": "string", "enum": [ "email_required", "email_optional", "off" ] }, "hide_when_offline": { "default": false, "type": "boolean" }, "theme": { "default": "light", "type": "string", "enum": [ "light", "dark", "auto" ] }, "transcript_on_resolve": { "default": false, "type": "boolean" }, "bot_enabled": { "default": false, "type": "boolean" }, "notify_emails": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "allow_in_iframe": { "default": false, "type": "boolean" }, "email_from": { "default": null, "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "follow_up": { "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "mode": { "default": "fixed", "type": "string", "enum": [ "fixed", "ai" ] }, "after_minutes": { "default": 1440, "type": "integer", "minimum": 5, "maximum": 43200 }, "max": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "message": { "default": { "vi": "Mình vẫn ở đây nếu bạn cần hỗ trợ thêm nhé!", "en": "We're still here if you need anything else!" }, "type": "object", "properties": { "vi": { "default": "Mình vẫn ở đây nếu bạn cần hỗ trợ thêm nhé!", "type": "string", "maxLength": 1000 }, "en": { "default": "We're still here if you need anything else!", "type": "string", "maxLength": 1000 } } }, "ai_hint": { "default": "", "type": "string", "maxLength": 500 } } }, "social_proof": { "default": { "enabled": false, "source": "orders", "manual": [], "interval_seconds": 45, "max_per_session": 3 }, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "source": { "default": "orders", "type": "string", "enum": [ "orders", "manual" ] }, "manual": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "text": { "type": "string", "maxLength": 120 }, "city": { "type": "string", "maxLength": 60 } }, "required": [ "name", "text" ] } }, "interval_seconds": { "default": 45, "type": "integer", "minimum": 10, "maximum": 600 }, "max_per_session": { "default": 3, "type": "integer", "minimum": 1, "maximum": 20 } } }, "csat": { "default": { "enabled": false, "ask": { "vi": "Bạn đánh giá cuộc trò chuyện hôm nay thế nào?", "en": "How was your conversation today?" } }, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "ask": { "default": { "vi": "Bạn đánh giá cuộc trò chuyện hôm nay thế nào?", "en": "How was your conversation today?" }, "type": "object", "properties": { "vi": { "default": "Bạn đánh giá cuộc trò chuyện hôm nay thế nào?", "type": "string", "maxLength": 300 }, "en": { "default": "How was your conversation today?", "type": "string", "maxLength": 300 } } } } }, "conversion_tracking": { "default": { "enabled": false, "ga4_measurement_id": null, "ga4_api_secret": null, "meta_pixel_id": null, "meta_capi_token": null, "google_ads_conversion": null }, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "ga4_measurement_id": { "default": null, "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "ga4_api_secret": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "meta_pixel_id": { "default": null, "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "meta_capi_token": { "default": null, "anyOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ] }, "google_ads_conversion": { "default": null, "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] } } }, "auto_resolve_days": { "default": 3, "type": "integer", "minimum": 0, "maximum": 365 }, "ai": { "default": {}, "type": "object", "properties": { "mode": { "default": "off", "type": "string", "enum": [ "off", "when_offline", "first_responder", "draft" ] }, "draft_after_handoff": { "default": true, "type": "boolean" }, "model": { "default": null, "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "persona_name": { "default": "Trợ lý", "type": "string", "maxLength": 60 }, "instructions": { "default": "", "type": "string", "maxLength": 4000 }, "handoff_phrase": { "default": {}, "type": "object", "properties": { "vi": { "default": "Mình sẽ chuyển bạn tới nhân viên hỗ trợ ngay nhé.", "type": "string", "maxLength": 300 }, "en": { "default": "Let me connect you with a human agent.", "type": "string", "maxLength": 300 } } }, "max_bot_turns": { "default": 6, "type": "integer", "minimum": 1, "maximum": 20 }, "collect_email": { "default": true, "type": "boolean" }, "collect_info": { "default": true, "type": "boolean" }, "situations": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z0-9_-]{1,32}$" }, "name": { "type": "string", "maxLength": 80 }, "enabled": { "default": true, "type": "boolean" }, "once": { "default": true, "type": "boolean" }, "when": { "default": "topic", "type": "string", "enum": [ "every_message", "keywords", "topic" ] }, "keywords": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "topic": { "default": "", "type": "string", "maxLength": 300 }, "office_hours": { "default": "any", "type": "string", "enum": [ "any", "within", "outside" ] }, "channels": { "default": [], "maxItems": 12, "type": "array", "items": { "type": "string", "enum": [ "web", "zalo", "messenger", "email", "instagram", "tiktokshop", "zalo_personal", "tiktok", "whatsapp", "telegram", "x", "line" ] } }, "site_ids": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "instructions": { "default": "", "type": "string", "maxLength": 1000 }, "context": { "default": "", "type": "string", "maxLength": 2000 }, "then": { "default": "none", "type": "string", "enum": [ "none", "handoff", "add_agent", "stop", "spam" ] }, "agent_ids": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "id", "name" ] } } } }, "header": { "default": {}, "type": "object", "properties": { "subtitle": { "default": {}, "type": "object", "properties": { "vi": { "default": "", "type": "string", "maxLength": 120 }, "en": { "default": "", "type": "string", "maxLength": 120 } } }, "logo_url": { "default": null, "anyOf": [ { "type": "string", "maxLength": 500, "format": "uri" }, { "type": "null" } ] }, "profile": { "default": "agents", "type": "string", "enum": [ "agents", "agents_or_logo", "member", "business" ] }, "member_id": { "default": null, "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } } }, "greeting_options": { "default": {}, "type": "object", "properties": { "enabled": { "default": true, "type": "boolean" }, "on_mobile": { "default": true, "type": "boolean" }, "sender": { "default": "none", "type": "string", "enum": [ "none", "online_agent" ] }, "teaser_seconds": { "default": 0, "type": "integer", "minimum": 0, "maximum": 120 } } }, "contact": { "default": {}, "type": "object", "properties": { "zalo": { "default": false, "type": "boolean" }, "messenger": { "default": false, "type": "boolean" }, "phone": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\+?[0-9][0-9 .-]{5,19}$" }, { "type": "null" } ] }, "email": { "default": null, "anyOf": [ { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] } } }, "layout": { "default": {}, "type": "object", "properties": { "size": { "default": "m", "type": "string", "enum": [ "s", "m", "l" ] }, "offset": { "default": null, "anyOf": [ { "type": "object", "properties": { "bottom": { "type": "integer", "minimum": 0, "maximum": 400 }, "side": { "type": "integer", "minimum": 0, "maximum": 400 } }, "required": [ "bottom", "side" ] }, { "type": "null" } ] }, "mobile_offset": { "default": null, "anyOf": [ { "type": "object", "properties": { "bottom": { "type": "integer", "minimum": 0, "maximum": 400 }, "side": { "type": "integer", "minimum": 0, "maximum": 400 } }, "required": [ "bottom", "side" ] }, { "type": "null" } ] } } }, "prechat": { "default": {}, "type": "object", "properties": { "enabled": { "default": false, "type": "boolean" }, "fields": { "default": {}, "type": "object", "properties": { "name": { "default": "optional", "type": "string", "enum": [ "off", "optional", "required" ] }, "phone": { "default": "required", "type": "string", "enum": [ "off", "optional", "required" ] }, "email": { "default": "off", "type": "string", "enum": [ "off", "optional", "required" ] } } } } }, "visibility": { "default": {}, "type": "object", "properties": { "devices": { "default": "all", "type": "string", "enum": [ "all", "desktop", "mobile" ] }, "url_include": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "url_exclude": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } } } }, "notifications": { "default": {}, "type": "object", "properties": { "sound": { "default": true, "type": "boolean" }, "title_alert": { "default": true, "type": "boolean" } } } } }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } }, "ChatSite": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_site" }, "id": { "type": "string" }, "website_id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "allowed_origins": { "type": "array", "items": { "type": "string" } }, "settings": { "type": "object" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "website_id", "name", "domain", "allowed_origins", "settings", "status", "created_at" ] }, "ChatVisitor": { "type": "object", "properties": { "id": { "type": "string" }, "site_id": { "type": "string" }, "channel": { "type": "string", "enum": [ "web", "zalo", "messenger", "email", "instagram", "tiktokshop", "zalo_personal", "tiktok", "whatsapp", "telegram", "x", "line" ] }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "custom_data": { "type": "object" }, "locale": { "type": [ "string", "null" ] }, "browser": { "type": [ "string", "null" ] }, "os": { "type": [ "string", "null" ] }, "device": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "current_url": { "type": [ "string", "null" ] }, "current_title": { "type": [ "string", "null" ] }, "referrer": { "type": [ "string", "null" ] }, "utm": { "type": "object", "additionalProperties": { "type": "string" } }, "visits": { "type": "integer" }, "customer_id": { "type": [ "string", "null" ] }, "first_seen_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "identified_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "site_id", "channel", "email", "name", "phone", "avatar_url", "external_id", "custom_data", "locale", "browser", "os", "device", "country", "city", "current_url", "current_title", "referrer", "utm", "visits", "customer_id", "first_seen_at", "last_seen_at", "identified_at" ] }, "ChatCustomer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "owner_id": { "type": [ "string", "null" ] }, "stage": { "type": "string", "enum": [ "new", "contacted", "qualified", "customer", "lost" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "object" }, "note": { "type": [ "string", "null" ] }, "channels": { "type": "array", "items": { "type": "string" } }, "first_seen_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "visitors": { "type": "array", "items": { "$ref": "#/components/schemas/ChatVisitor" } } }, "required": [ "id", "stage", "labels", "fields", "channels", "first_seen_at", "last_seen_at", "created_at", "updated_at" ] }, "ChatCustomerUpdate": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "owner_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "stage": { "type": "string", "enum": [ "new", "contacted", "qualified", "customer", "lost" ] }, "labels": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "fields": { "type": "object", "propertyNames": { "type": "string", "maxLength": 60 }, "additionalProperties": {} }, "note": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } } }, "ChatCustomerField": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "select", "boolean" ] }, "options": { "type": "array", "items": { "type": "string" } }, "position": { "type": "integer" }, "ai_collect": { "type": "boolean" }, "ai_hint": { "type": "string" } }, "required": [ "id", "key", "label", "type", "options", "position", "ai_collect", "ai_hint" ] }, "ChatCustomerFieldRequest": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 60 }, "key": { "type": "string", "pattern": "^[a-z0-9_]{1,40}$" }, "type": { "default": "text", "type": "string", "enum": [ "text", "number", "date", "select", "boolean" ] }, "options": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "ai_collect": { "default": false, "type": "boolean" }, "ai_hint": { "default": "", "type": "string", "maxLength": 200 } }, "required": [ "label" ] }, "ChatCustomerFieldPatch": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 60 }, "type": { "type": "string", "enum": [ "text", "number", "date", "select", "boolean" ] }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "ai_collect": { "type": "boolean" }, "ai_hint": { "type": "string", "maxLength": 200 } } }, "ChatLiveVisitor": { "type": "object", "properties": { "id": { "type": "string" }, "site_id": { "type": "string" }, "site_name": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "page_url": { "type": [ "string", "null" ] }, "page_title": { "type": [ "string", "null" ] }, "referrer": { "type": [ "string", "null" ] }, "utm": { "type": "object", "additionalProperties": { "type": "string" } }, "visits": { "type": "integer" }, "device": { "type": [ "string", "null" ] }, "browser": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "online_since": { "type": [ "string", "null" ], "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "site_id", "site_name", "name", "email", "phone", "page_url", "page_title", "referrer", "utm", "visits", "device", "browser", "country", "city", "customer_id", "conversation_id", "online_since", "last_seen_at" ] }, "ChatGreetRequest": { "type": "object", "properties": { "visitor_id": { "type": "string", "maxLength": 64 }, "content": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "visitor_id", "content" ] }, "ChatProductRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "sku": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "price": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000000000 }, "compare_at_price": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000000000 }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri" }, { "type": "null" } ] }, "app_store_product_id": { "anyOf": [ { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9._-]+$" }, { "type": "null" } ] }, "play_product_id": { "anyOf": [ { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9._-]+$" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "stock": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "variants": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "sku": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000000000 }, { "type": "null" } ] }, "stock": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name" ] } }, "active": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "physical", "digital", "service", "subscription", "consumable", "non_consumable" ] }, "billing_period": { "anyOf": [ { "type": "string", "enum": [ "P1W", "P1M", "P3M", "P6M", "P1Y" ] }, { "type": "null" } ] }, "trial_days": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 365 }, { "type": "null" } ] }, "prices": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "ios", "android" ] }, "variant": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "amount": { "type": "number", "minimum": 0, "maximum": 100000000000 }, "currency": { "default": "VND", "type": "string", "pattern": "^[A-Z]{3}$" }, "store_product_id": { "anyOf": [ { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9._-]+$" }, { "type": "null" } ] }, "base_plan_id": { "anyOf": [ { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9._-]+$" }, { "type": "null" } ] }, "offer_id": { "anyOf": [ { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9._-]+$" }, { "type": "null" } ] } }, "required": [ "platform", "amount" ] } } }, "required": [ "name" ] }, "ChatSubscriptionRequest": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "trial", "active", "grace", "on_hold", "paused", "canceled", "expired", "refunded", "revoked" ] }, "store_product_id": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "base_plan_id": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "product_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "external_user_id": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "account_token": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "customer_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "auto_renew": { "type": [ "boolean", "null" ] }, "environment": { "type": "string", "enum": [ "production", "sandbox" ] }, "started_at": { "anyOf": [ {}, { "type": "null" } ] }, "current_period_end": { "anyOf": [ {}, { "type": "null" } ] }, "canceled_at": { "anyOf": [ {}, { "type": "null" } ] }, "amount": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] }, "event": { "type": "string", "maxLength": 60 }, "event_at": {} }, "required": [ "status" ] }, "ChatSubscription": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_subscription" }, "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "web", "ios", "android" ] }, "original_id": { "type": "string" }, "status": { "type": "string", "enum": [ "trial", "active", "grace", "on_hold", "paused", "canceled", "expired", "refunded", "revoked" ] }, "entitled": { "type": "boolean" }, "product_id": { "type": [ "string", "null" ] }, "product_name": { "type": [ "string", "null" ] }, "store_product_id": { "type": [ "string", "null" ] }, "base_plan_id": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ] }, "external_user_id": { "type": [ "string", "null" ] }, "auto_renew": { "type": [ "boolean", "null" ] }, "environment": { "type": "string", "enum": [ "production", "sandbox" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "current_period_end": { "type": [ "string", "null" ], "format": "date-time" }, "canceled_at": { "type": [ "string", "null" ], "format": "date-time" }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "platform", "original_id", "status", "entitled", "product_id", "product_name", "store_product_id", "base_plan_id", "customer_id", "external_user_id", "auto_renew", "environment", "started_at", "current_period_end", "canceled_at", "amount", "currency", "updated_at" ] }, "ChatStorePurchase": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_store_purchase" }, "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "transaction_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "consumable", "non_consumable", "non_renewing" ] }, "status": { "type": "string", "enum": [ "purchased", "refunded" ] }, "product_id": { "type": [ "string", "null" ] }, "product_name": { "type": [ "string", "null" ] }, "store_product_id": { "type": "string" }, "quantity": { "type": "integer" }, "customer_id": { "type": [ "string", "null" ] }, "external_user_id": { "type": [ "string", "null" ] }, "environment": { "type": "string", "enum": [ "production", "sandbox" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "purchased_at": { "type": [ "string", "null" ], "format": "date-time" }, "refunded_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "platform", "transaction_id", "kind", "status", "product_id", "product_name", "store_product_id", "quantity", "customer_id", "external_user_id", "environment", "amount", "currency", "purchased_at", "refunded_at" ] }, "ChatProductImportRequest": { "type": "object", "properties": { "csv": { "type": "string", "maxLength": 5000000 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "site_url": { "type": "string", "maxLength": 2048, "format": "uri" } } }, "ChatProduct": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_product" }, "id": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "price": { "type": "integer" }, "compare_at_price": { "type": [ "integer", "null" ] }, "currency": { "type": "string" }, "image_url": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "app_store_product_id": { "type": [ "string", "null" ] }, "play_product_id": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "physical", "digital", "service", "subscription", "consumable", "non_consumable" ] }, "billing_period": { "type": [ "string", "null" ], "enum": [ "P1W", "P1M", "P3M", "P6M", "P1Y", null ] }, "trial_days": { "type": [ "integer", "null" ] }, "prices": { "type": "array", "description": "App Store and Google Play prices; price, currency and url are the web price", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "ios", "android" ] }, "variant": { "type": [ "string", "null" ] }, "amount": { "type": "number" }, "currency": { "type": "string" }, "store_product_id": { "type": [ "string", "null" ] }, "base_plan_id": { "type": [ "string", "null" ] }, "offer_id": { "type": [ "string", "null" ] } }, "required": [ "platform", "amount", "currency" ] } }, "category": { "type": [ "string", "null" ] }, "stock": { "type": [ "integer", "null" ] }, "variants": { "type": "array", "items": { "type": "object" } }, "active": { "type": "boolean" }, "source": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "sku", "name", "description", "price", "compare_at_price", "currency", "image_url", "url", "app_store_product_id", "play_product_id", "kind", "billing_period", "trial_days", "prices", "category", "stock", "variants", "active", "source", "external_id", "created_at", "updated_at" ] }, "ChatOrderRequest": { "type": "object", "properties": { "conversation_id": { "type": "string", "maxLength": 64 }, "customer_id": { "type": "string", "maxLength": 64 }, "items": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "product_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "sku": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "price": { "type": "integer", "minimum": 0, "maximum": 100000000000 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "required": [ "name", "price", "quantity" ] } }, "discount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000000000 }, "shipping": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000000000 }, "shipping_address": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } } }, "note": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "new", "consulting", "confirmed", "shipping", "done", "cancelled" ] }, "invoice": { "type": "boolean" }, "send_card": { "type": "boolean" } }, "required": [ "items" ] }, "ChatOrderUpdate": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "product_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "sku": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "price": { "type": "integer", "minimum": 0, "maximum": 100000000000 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "required": [ "name", "price", "quantity" ] } }, "discount": { "type": "integer", "minimum": 0, "maximum": 100000000000 }, "shipping": { "type": "integer", "minimum": 0, "maximum": 100000000000 }, "shipping_address": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } } }, "note": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "new", "consulting", "confirmed", "shipping", "done", "cancelled" ] }, "invoice": { "type": "boolean" } } }, "ChatOrderItem": { "type": "object", "properties": { "product_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "variant": { "type": [ "string", "null" ] }, "price": { "type": "integer" }, "quantity": { "type": "integer" } }, "required": [ "name", "price", "quantity" ] }, "ChatOrder": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_order" }, "id": { "type": "string" }, "code": { "type": "string" }, "number": { "type": "integer" }, "status": { "type": "string", "enum": [ "new", "consulting", "confirmed", "shipping", "done", "cancelled" ] }, "customer_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "visitor_id": { "type": [ "string", "null" ] }, "agent_id": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChatOrderItem" } }, "subtotal": { "type": "integer" }, "discount": { "type": "integer" }, "shipping": { "type": "integer" }, "total": { "type": "integer" }, "currency": { "type": "string" }, "shipping_address": { "type": "object" }, "note": { "type": [ "string", "null" ] }, "payment_id": { "type": [ "string", "null" ] }, "payment_status": { "type": "string", "enum": [ "unpaid", "paid" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "invoice": { "type": "boolean" }, "draft": { "type": "boolean" }, "source": { "type": "string", "description": "manual, or the channel the order was mirrored from (e.g. tiktokshop)" }, "external_id": { "type": [ "string", "null" ] }, "external_status": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "code", "number", "status", "customer_id", "conversation_id", "visitor_id", "agent_id", "items", "subtotal", "discount", "shipping", "total", "currency", "shipping_address", "note", "payment_id", "payment_status", "paid_at", "invoice", "draft", "source", "external_id", "external_status", "created_at", "updated_at" ] }, "ChatPaymentLinkRequest": { "type": "object", "properties": { "expires_in": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "send_card": { "default": true, "type": "boolean" } } }, "ChatTicketRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "type": { "default": "question", "type": "string", "enum": [ "question", "bug", "complaint", "request", "other" ] }, "priority": { "default": "normal", "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "status": { "type": "string", "enum": [ "open", "in_progress", "waiting", "resolved", "closed" ] }, "customer_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "conversation_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "assignee_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "due_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "title" ] }, "ChatTicketUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "type": { "default": "question", "type": "string", "enum": [ "question", "bug", "complaint", "request", "other" ] }, "priority": { "default": "normal", "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "status": { "type": "string", "enum": [ "open", "in_progress", "waiting", "resolved", "closed" ] }, "customer_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "conversation_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "assignee_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "due_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } } }, "ChatTicket": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_ticket" }, "id": { "type": "string" }, "code": { "type": "string" }, "number": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "question", "bug", "complaint", "request", "other" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "status": { "type": "string", "enum": [ "open", "in_progress", "waiting", "resolved", "closed" ] }, "customer_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "assignee_id": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "sla": { "type": "object" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "code", "number", "title", "description", "type", "priority", "status", "customer_id", "conversation_id", "assignee_id", "created_by", "tags", "due_at", "sla", "resolved_at", "closed_at", "created_at", "updated_at" ] }, "ChatSlaPolicy": { "type": "object", "properties": { "urgent": { "default": { "first_response_minutes": 15, "resolve_minutes": 240 }, "type": "object", "properties": { "first_response_minutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "resolve_minutes": { "type": "integer", "minimum": 1, "maximum": 129600 } }, "required": [ "first_response_minutes", "resolve_minutes" ] }, "high": { "default": { "first_response_minutes": 60, "resolve_minutes": 480 }, "type": "object", "properties": { "first_response_minutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "resolve_minutes": { "type": "integer", "minimum": 1, "maximum": 129600 } }, "required": [ "first_response_minutes", "resolve_minutes" ] }, "normal": { "default": { "first_response_minutes": 240, "resolve_minutes": 1440 }, "type": "object", "properties": { "first_response_minutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "resolve_minutes": { "type": "integer", "minimum": 1, "maximum": 129600 } }, "required": [ "first_response_minutes", "resolve_minutes" ] }, "low": { "default": { "first_response_minutes": 1440, "resolve_minutes": 4320 }, "type": "object", "properties": { "first_response_minutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "resolve_minutes": { "type": "integer", "minimum": 1, "maximum": 129600 } }, "required": [ "first_response_minutes", "resolve_minutes" ] } } }, "ChatProfileLink": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id (assigned as pl_… when you save a link without one)." }, "label": { "type": "string", "maxLength": 40, "description": "What agents see on the link, e.g. \"Admin\"." }, "url": { "type": "string", "maxLength": 500, "description": "https URL template. Variables: {{user_id}} (the verified identify() user id, else the id the visitor claimed without verification, in which case agents see the link marked unverified), {{email}}, {{phone}}, {{name}}, {{customer_id}}, {{conversation_id}}, {{site_id}}, {{field.}} (a customer field), {{data.}} (the visitor's custom data, always marked unverified). Rules: https only, variables only after the host (never in the domain), at most 500 characters. Values are URL-encoded; a link whose variables have no value in a conversation is not shown." }, "site_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Only show the link in conversations of these sites; absent or empty = every site." } }, "required": [ "id", "label", "url" ], "description": "A profile link: the business's own URL for the person in a conversation (their page in your admin, an orders search…), filled per conversation for agents. At most 10 per business." }, "ChatProfileLinksRequest": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 10, "description": "The full list, in display order; it replaces the saved one. Omit id for new links.", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 40 }, "label": { "type": "string", "maxLength": 40 }, "url": { "type": "string", "maxLength": 500 }, "site_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } }, "required": [ "label", "url" ] } } }, "required": [ "data" ] }, "ChatZnsSendRequest": { "type": "object", "properties": { "account_id": { "type": "string", "maxLength": 64 }, "template_id": { "type": "string", "maxLength": 40 }, "phone": { "type": "string", "minLength": 9, "maxLength": 20 }, "template_data": { "type": "object", "propertyNames": { "type": "string", "maxLength": 60 }, "additionalProperties": { "type": "string", "maxLength": 500 } }, "customer_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "order_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "tracking_id": { "type": "string", "maxLength": 60 } }, "required": [ "account_id", "template_id", "phone", "template_data" ] }, "ChatZnsBulkRequest": { "type": "object", "properties": { "account_id": { "type": "string", "maxLength": 64 }, "template_id": { "type": "string", "maxLength": 40 }, "mapping": { "type": "object", "propertyNames": { "type": "string", "maxLength": 60 }, "additionalProperties": { "type": "string", "maxLength": 500 } }, "filters": { "type": "object", "properties": { "q": { "type": "string", "maxLength": 200 }, "stage": { "type": "string", "enum": [ "new", "contacted", "qualified", "customer", "lost" ] }, "owner_id": { "type": "string", "maxLength": 64 }, "label": { "type": "string", "maxLength": 40 }, "channel": { "type": "string", "enum": [ "web", "zalo", "messenger", "email", "instagram", "tiktokshop", "zalo_personal", "tiktok", "whatsapp", "telegram", "x", "line" ] } } }, "limit": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 5000 } }, "required": [ "account_id", "template_id", "mapping" ] }, "ChatZnsMessage": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_zns_message" }, "id": { "type": "string" }, "account_id": { "type": "string" }, "customer_id": { "type": [ "string", "null" ] }, "order_id": { "type": [ "string", "null" ] }, "phone": { "type": "string" }, "template_id": { "type": "string" }, "template_name": { "type": [ "string", "null" ] }, "template_data": { "type": "object" }, "tracking_id": { "type": [ "string", "null" ] }, "msg_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "sent", "failed" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "account_id", "customer_id", "order_id", "phone", "template_id", "template_name", "template_data", "tracking_id", "msg_id", "status", "error", "created_at" ] }, "ChatZnsTemplate": { "type": "object", "properties": { "templateId": { "type": "string" }, "templateName": { "type": "string" }, "status": { "type": "string" }, "templateQuality": { "type": "string" }, "price": { "type": "string" }, "listParams": { "type": "array", "items": { "type": "object" } } }, "required": [ "templateId", "templateName" ] }, "ChatReport": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_report" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "overview": { "type": "object" }, "daily": { "type": "array", "items": { "type": "object" } }, "agents": { "type": "array", "items": { "type": "object" } }, "tags": { "type": "array", "items": { "type": "object" } }, "channels": { "type": "array", "items": { "type": "object" } }, "ai": { "type": "object", "description": "Assistant share, CSAT of AI-only vs human conversations, spend, hand-off reasons, open knowledge gaps" } }, "required": [ "object", "from", "to", "overview", "daily", "agents", "tags", "channels", "ai" ] }, "ChatRating": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_rating" }, "conversation_id": { "type": "string" }, "site_id": { "type": "string" }, "visitor_id": { "type": "string" }, "agent_id": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "score": { "type": "integer" }, "comment": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "conversation_id", "site_id", "visitor_id", "agent_id", "channel", "score", "comment", "created_at" ] }, "ChatFlowRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "site_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "trigger": { "type": "object", "properties": { "kind": { "default": "conversation_start", "type": "string", "enum": [ "conversation_start", "keyword", "url", "manual" ] }, "keywords": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "url_contains": { "type": "string", "maxLength": 200 }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "web", "zalo", "messenger", "email", "instagram", "tiktokshop", "zalo_personal", "tiktok", "whatsapp", "telegram", "x", "line" ] } }, "office_hours": { "default": "any", "type": "string", "enum": [ "any", "within", "outside" ] }, "ref": { "type": "string", "maxLength": 60 } } }, "steps": { "minItems": 1, "maxItems": 60, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "message" }, "text": { "type": "string", "minLength": 1, "maxLength": 2000 }, "quick_replies": { "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } } }, "required": [ "id", "type", "text" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "products" }, "product_ids": { "maxItems": 5, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "query": { "type": "string", "maxLength": 200 }, "text": { "type": "string", "maxLength": 500 } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "ask" }, "text": { "type": "string", "minLength": 1, "maxLength": 2000 }, "save_to": { "type": "string", "pattern": "^(name|phone|email|field:[a-z0-9_]{1,40}|var:[a-z0-9_]{1,40})$" }, "quick_replies": { "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "validate": { "default": "none", "type": "string", "enum": [ "none", "phone", "email" ] }, "retry_text": { "type": "string", "maxLength": 500 } }, "required": [ "id", "type", "text", "save_to" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "branch" }, "on": { "default": "last", "type": "string", "pattern": "^(last|var:[a-z0-9_]{1,40})$" }, "rules": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "contains": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "if": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "pattern": "^(channel|site_id|status|tag|assignee|office_hours|has_phone|has_email|ref|rating|order_total|order_status|field:[a-z0-9_]{1,40})$" }, "op": { "default": "eq", "type": "string", "enum": [ "eq", "neq", "contains", "gt", "lt", "exists", "not_exists" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "field" ] } }, "goto": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "goto" ] } }, "else_goto": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "id", "type", "rules" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "delay" }, "seconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "id", "type", "seconds" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "tag" }, "tags": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } } }, "required": [ "id", "type", "tags" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "assign" }, "user_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "webhook" }, "name": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "id", "type", "name" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "goto" }, "goto": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "id", "type", "goto" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "to_ai" } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "to_human" }, "text": { "type": "string", "maxLength": 500 } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "const": "end" } }, "required": [ "id", "type" ] } ] } } }, "required": [ "name", "trigger", "steps" ] }, "ChatWorkflowRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "site_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "trigger": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "conversation_created", "conversation_resolved", "handoff", "assigned", "tagged", "rated", "order_created", "order_paid", "lead", "visitor_waiting", "order_unpaid" ] }, "minutes": { "type": "integer", "minimum": 1, "maximum": 43200 }, "tag": { "type": "string", "maxLength": 40 }, "match": { "default": "all", "type": "string", "enum": [ "all", "any" ] }, "conditions": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "pattern": "^(channel|site_id|status|tag|assignee|office_hours|has_phone|has_email|ref|rating|order_total|order_status|field:[a-z0-9_]{1,40})$" }, "op": { "default": "eq", "type": "string", "enum": [ "eq", "neq", "contains", "gt", "lt", "exists", "not_exists" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "field" ] } } }, "required": [ "event" ] }, "steps": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "send_message" }, "text": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "ai_message" }, "instruction": { "type": "string", "minLength": 1, "maxLength": 1000 }, "fallback": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "type", "instruction" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "send_email" }, "subject": { "type": "string", "minLength": 1, "maxLength": 200 }, "text": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "type", "subject", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "send_zns" }, "account_id": { "type": "string", "maxLength": 64 }, "template_id": { "type": "string", "minLength": 1, "maxLength": 64 }, "data": { "default": {}, "type": "object", "propertyNames": { "type": "string", "maxLength": 60 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "type", "account_id", "template_id" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "tag" }, "add": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "remove": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "assign" }, "user_id": { "default": null, "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "notify" }, "user_ids": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "text": { "default": "", "type": "string", "maxLength": 1000 } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "create_reminder" }, "minutes": { "default": 60, "type": "integer", "minimum": 0, "maximum": 43200 }, "note": { "default": "", "type": "string", "maxLength": 500 }, "user_id": { "default": null, "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "set_status" }, "status": { "type": "string", "enum": [ "open", "pending", "resolved" ] } }, "required": [ "type", "status" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "conversion" }, "name": { "type": "string", "enum": [ "lead", "purchase" ] } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "webhook" }, "name": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "type", "name" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "wait" }, "minutes": { "type": "integer", "minimum": 1, "maximum": 43200 } }, "required": [ "type", "minutes" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "condition" }, "match": { "default": "all", "type": "string", "enum": [ "all", "any" ] }, "conditions": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "pattern": "^(channel|site_id|status|tag|assignee|office_hours|has_phone|has_email|ref|rating|order_total|order_status|field:[a-z0-9_]{1,40})$" }, "op": { "default": "eq", "type": "string", "enum": [ "eq", "neq", "contains", "gt", "lt", "exists", "not_exists" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "field" ] } } }, "required": [ "type", "conditions" ] } ] } } }, "required": [ "name", "trigger", "steps" ] }, "ChatWorkflowTemplate": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "workflow": { "type": "object" } }, "required": [ "key", "name", "description", "workflow" ] }, "ChatWorkflow": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_workflow" }, "id": { "type": "string" }, "site_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "trigger": { "type": "object" }, "steps": { "type": "array", "items": { "type": "object" } }, "started": { "type": "integer" }, "completed": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "site_id", "name", "enabled", "trigger", "steps", "started", "completed", "created_at", "updated_at" ] }, "ChatWorkflowRun": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_workflow_run" }, "id": { "type": "string" }, "workflow_id": { "type": "string" }, "conversation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "waiting", "done", "stopped", "failed" ] }, "step": { "type": "integer" }, "event": { "type": "object" }, "log": { "type": "array", "items": { "type": "object" } }, "resume_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "workflow_id", "conversation_id", "status", "step", "event", "log", "resume_at", "error", "created_at", "updated_at" ] }, "ChatFlow": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_flow" }, "id": { "type": "string" }, "site_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "trigger": { "type": "object" }, "steps": { "type": "array", "items": { "type": "object" } }, "position": { "type": "integer" }, "started": { "type": "integer" }, "completed": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "site_id", "name", "enabled", "trigger", "steps", "position", "started", "completed", "created_at", "updated_at" ] }, "ChatFlowTemplate": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "trigger": { "type": "object" }, "steps": { "type": "array", "items": { "type": "object" } } }, "required": [ "key", "name", "description", "trigger", "steps" ] }, "ChatCampaignRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "site_id": { "type": "string", "maxLength": 64 }, "enabled": { "type": "boolean" }, "kind": { "default": "message", "type": "string", "enum": [ "message", "form" ] }, "trigger": { "type": "object", "properties": { "seconds_on_page": { "type": "integer", "minimum": 0, "maximum": 3600 }, "scroll_percent": { "type": "integer", "minimum": 1, "maximum": 100 }, "exit_intent": { "type": "boolean" }, "url_contains": { "type": "string", "maxLength": 200 }, "url_excludes": { "type": "string", "maxLength": 200 }, "referrer_contains": { "type": "string", "maxLength": 200 }, "utm_source": { "type": "string", "maxLength": 60 }, "returning": { "default": "any", "type": "string", "enum": [ "any", "new", "returning" ] }, "device": { "default": "any", "type": "string", "enum": [ "any", "mobile", "desktop" ] }, "only_without_conversation": { "default": true, "type": "boolean" }, "only_when_online": { "default": false, "type": "boolean" } } }, "content": { "type": "object", "properties": { "text": { "type": "object", "properties": { "vi": { "default": "", "type": "string", "maxLength": 500 }, "en": { "default": "", "type": "string", "maxLength": 500 } } }, "buttons": { "maxItems": 3, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } }, "fields": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "name", "phone", "email" ] } }, "submit_label": { "type": "object", "properties": { "vi": { "default": "Gửi", "type": "string", "maxLength": 40 }, "en": { "default": "Send", "type": "string", "maxLength": 40 } } }, "thanks": { "type": "object", "properties": { "vi": { "default": "Cảm ơn bạn! Đội ngũ sẽ liên hệ sớm.", "type": "string", "maxLength": 300 }, "en": { "default": "Thanks! We'll be in touch shortly.", "type": "string", "maxLength": 300 } } } }, "required": [ "text" ] }, "frequency": { "default": "once", "type": "string", "enum": [ "once", "session", "always" ] } }, "required": [ "name", "site_id", "trigger", "content" ] }, "ChatCampaign": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_campaign" }, "id": { "type": "string" }, "site_id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "message", "form" ] }, "trigger": { "type": "object" }, "content": { "type": "object" }, "frequency": { "type": "string", "enum": [ "once", "session", "always" ] }, "position": { "type": "integer" }, "shown": { "type": "integer" }, "clicked": { "type": "integer" }, "leads": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "site_id", "name", "enabled", "kind", "trigger", "content", "frequency", "position", "shown", "clicked", "leads", "created_at", "updated_at" ] }, "ChatPaymentLink": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_payment_link" }, "order": { "$ref": "#/components/schemas/ChatOrder" }, "id": { "type": "string" }, "order_id": { "type": [ "string", "null" ] }, "order_code": { "type": [ "string", "null" ] }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "checkout_url": { "type": "string" }, "qr_image_url": { "type": "string" }, "qr_payload": { "type": "string" }, "code": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" } }, "required": [ "object", "order", "id", "order_id", "order_code", "amount", "currency", "checkout_url", "qr_image_url", "qr_payload", "code", "expires_at", "status" ] }, "ChatConversation": { "type": "object", "properties": { "id": { "type": "string" }, "site_id": { "type": "string" }, "visitor_id": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ] }, "assignee_kind": { "type": [ "string", "null" ] }, "assignee_id": { "type": [ "string", "null" ] }, "member_ids": { "type": "array", "items": { "type": "string" } }, "flag": { "type": [ "string", "null" ], "enum": [ "hidden", "spam", null ] }, "seq": { "type": "integer" }, "visitor_unread": { "type": "integer" }, "agent_unread": { "type": "integer" }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_message_preview": { "type": [ "string", "null" ] }, "last_message_sender_type": { "type": [ "string", "null" ] }, "first_response_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string" } }, "subject": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "visitor": { "$ref": "#/components/schemas/ChatVisitor" }, "journey": { "oneOf": [ { "$ref": "#/components/schemas/ChatConversationJourney" }, { "type": "null" } ], "description": "What the visitor did on the website or app before the conversation started (pages, app screens, custom events), newest last, at most 20 steps. Absent when nothing was recorded." } }, "required": [ "id", "site_id", "visitor_id", "channel", "status", "seq", "tags", "created_at", "updated_at" ] }, "ChatJourneyItem": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "page", "screen", "event" ] }, "at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "maxLength": 500, "description": "page: the URL (secret-looking query parameters read [redacted])" }, "title": { "type": "string", "maxLength": 200, "description": "page: the document title" }, "screen": { "type": "string", "maxLength": 200, "description": "screen: the app screen name" }, "params": { "type": "object", "description": "screen: its parameters (at most 1 KB of JSON)" }, "name": { "type": "string", "maxLength": 200, "description": "event: the pushEvent name" }, "data": { "type": "object", "description": "event: its data (at most 1 KB of JSON; values under keys like password, token, secret, card, cvv or otp read [redacted])" } }, "required": [ "kind", "at" ] }, "ChatConversationJourney": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/ChatJourneyItem" } }, "captured_at": { "type": "string", "format": "date-time" } }, "required": [ "items", "captured_at" ] }, "ChatConversationUpdate": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ] }, "assignee_id": { "type": [ "string", "null" ] }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 40 } }, "member_ids": { "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "flag": { "anyOf": [ { "type": "string", "enum": [ "hidden", "spam" ] }, { "type": "null" } ] } } }, "ChatMessageRequest": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 }, "visibility": { "default": "public", "type": "string", "enum": [ "public", "private" ] }, "attachments": { "maxItems": 5, "type": "array", "items": { "type": "string" } }, "sender_name": { "type": "string", "maxLength": 100 }, "metadata": { "type": "object", "propertyNames": { "type": "string", "maxLength": 40 }, "additionalProperties": {} } }, "required": [ "content" ] }, "ChatTimelineItem": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "message", "event" ] }, "id": { "type": "string" }, "conversation_id": { "type": "string" }, "seq": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "sender_type": { "type": "string" }, "content": { "type": "string" }, "visibility": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object" } }, "type": { "type": "string" }, "data": { "type": "object" } }, "required": [ "kind", "id", "conversation_id", "seq", "created_at" ] }, "ChatVisitorUpdate": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "custom_data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "ChatCannedRequest": { "type": "object", "properties": { "shortcut": { "type": "string", "pattern": "^[a-z0-9-]{1,63}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "content": { "type": "string", "minLength": 1, "maxLength": 5000 }, "subject": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "is_private": { "type": "boolean" }, "locale": { "anyOf": [ { "type": "string", "enum": [ "vi", "en" ] }, { "type": "null" } ] } }, "required": [ "shortcut", "title", "content" ] }, "ChatRoutingRuleRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "enabled": { "default": true, "type": "boolean" }, "conditions": { "default": {}, "type": "object", "properties": { "channels": { "maxItems": 12, "type": "array", "items": { "type": "string", "enum": [ "web", "zalo", "messenger", "email", "instagram", "tiktokshop", "zalo_personal", "tiktok", "whatsapp", "telegram", "x", "line" ] } }, "siteIds": { "maxItems": 50, "type": "array", "items": { "type": "string" } }, "channelAccountIds": { "maxItems": 50, "type": "array", "items": { "type": "string" } }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "keywords": { "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 100 } }, "withinOfficeHours": { "type": "boolean" } } }, "strategy": { "default": "round_robin", "type": "string", "enum": [ "round_robin", "least_busy", "specific", "unassigned" ] }, "agentIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string" } }, "preferPrevious": { "default": true, "type": "boolean" }, "preferOwner": { "default": true, "type": "boolean" }, "onlineOnly": { "default": true, "type": "boolean" }, "createTicket": { "default": false, "type": "boolean" }, "ticketPriority": { "default": "normal", "type": "string", "enum": [ "low", "normal", "high", "urgent" ] } }, "required": [ "name" ] }, "ChatRoutingRule": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_routing_rule" }, "id": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "integer" }, "enabled": { "type": "boolean" }, "conditions": { "type": "object" }, "strategy": { "type": "string", "enum": [ "round_robin", "least_busy", "specific", "unassigned" ] }, "agent_ids": { "type": "array", "items": { "type": "string" } }, "prefer_previous": { "type": "boolean" }, "prefer_owner": { "type": "boolean" }, "online_only": { "type": "boolean" }, "create_ticket": { "type": "boolean" }, "ticket_priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "position", "enabled", "conditions", "strategy", "agent_ids", "prefer_previous", "prefer_owner", "online_only", "create_ticket", "ticket_priority", "created_at" ] }, "ChatKbSourceRequest": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "faq", "text", "url" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "url": { "type": "string", "maxLength": 2000, "format": "uri" }, "content": { "type": "string", "maxLength": 200000 }, "refresh_days": { "default": 7, "type": "integer", "minimum": 0, "maximum": 90 } }, "required": [ "kind", "title" ] }, "KnowledgeDocumentRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "content": { "type": "string", "minLength": 1, "maxLength": 200000 }, "url": { "anyOf": [ { "type": "string", "maxLength": 2000, "format": "uri" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string", "pattern": "^[a-z]{2,3}(-[a-z0-9]{2,8})?$" }, { "type": "null" } ] }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 } }, "collection": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,100}$" }, { "type": "null" } ] } }, "required": [ "title", "content" ] }, "KnowledgeBatchRequest": { "type": "object", "properties": { "documents": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "content": { "type": "string", "minLength": 1, "maxLength": 200000 }, "url": { "anyOf": [ { "type": "string", "maxLength": 2000, "format": "uri" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string", "pattern": "^[a-z]{2,3}(-[a-z0-9]{2,8})?$" }, { "type": "null" } ] }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 } }, "collection": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,100}$" }, { "type": "null" } ] }, "external_id": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,200}$" } }, "required": [ "title", "content", "external_id" ] } } }, "required": [ "documents" ] }, "KnowledgeSyncRequest": { "type": "object", "properties": { "documents": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "content": { "type": "string", "minLength": 1, "maxLength": 200000 }, "url": { "anyOf": [ { "type": "string", "maxLength": 2000, "format": "uri" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string", "pattern": "^[a-z]{2,3}(-[a-z0-9]{2,8})?$" }, { "type": "null" } ] }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 } }, "external_id": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,200}$" } }, "required": [ "title", "content", "external_id" ] } } }, "required": [ "documents" ] }, "KnowledgeDocument": { "type": "object", "properties": { "object": { "type": "string", "const": "knowledge_document" }, "id": { "type": "string", "description": "Your id for the document" }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "collection": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "indexing", "indexed", "error" ] }, "error": { "type": [ "string", "null" ] }, "chunk_count": { "type": "integer" }, "last_indexed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "changed": { "type": "boolean", "description": "On writes: false when the document was already exactly this (nothing re-indexed)" } }, "required": [ "object", "id", "title", "url", "locale", "tags", "collection", "status", "error", "chunk_count", "last_indexed_at", "created_at", "updated_at" ] }, "KnowledgeSync": { "type": "object", "properties": { "object": { "type": "string", "const": "knowledge_sync" }, "collection": { "type": "string" }, "written": { "type": "integer" }, "unchanged": { "type": "integer" }, "deleted": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeDocument" } } }, "required": [ "object", "collection", "written", "unchanged", "deleted", "data" ] }, "KnowledgeChunk": { "type": "object", "properties": { "object": { "type": "string", "const": "knowledge_chunk" }, "id": { "type": "string" }, "heading": { "type": "string" }, "content": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ] }, "score": { "type": "number" } }, "required": [ "object", "id", "heading", "content", "url", "locale", "score" ] }, "ChatKbSource": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_kb_source" }, "id": { "type": "string" }, "site_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "faq", "text", "url", "file" ] }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "indexing", "indexed", "error" ] }, "error": { "type": [ "string", "null" ] }, "pages": { "type": "integer" }, "chunk_count": { "type": "integer" }, "refresh_days": { "type": "integer" }, "last_indexed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "site_id", "kind", "title", "url", "status", "error", "pages", "chunk_count", "refresh_days", "last_indexed_at", "created_at" ] }, "ChatKbChunk": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_kb_chunk" }, "id": { "type": "string" }, "heading": { "type": "string" }, "content": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "score": { "type": "number" } }, "required": [ "object", "id", "heading", "content", "url", "score" ] }, "ChatCanned": { "type": "object", "properties": { "object": { "type": "string", "const": "chat_canned_response" }, "id": { "type": "string" }, "shortcut": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "subject": { "type": [ "string", "null" ], "description": "Email template subject" }, "is_private": { "type": "boolean" }, "locale": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "shortcut", "title", "content", "subject", "is_private", "locale", "created_at" ] }, "CreatePaymentRequest": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 100000000000, "description": "Amount in VND" }, "description": { "description": "Shown to the payer on the checkout page; the transfer description is the payment code", "type": "string", "maxLength": 200 }, "code": { "description": "Your own transfer description (your order number, say) instead of a generated code. Letters and digits only, 6 to 20 of them, upper-cased; unique per bank account, so reuse is refused with 409. Longer is safer: a short code that happens to appear in someone's transfer text would match that transfer.", "type": "string", "pattern": "^[A-Za-z0-9]{6,20}$" }, "connection_id": { "description": "Bank account to receive into. Defaults to the only active one.", "type": "string" }, "expires_in": { "description": "Seconds until the payment expires. Default 86400.", "type": "integer", "minimum": 1, "maximum": 2592000 }, "return_url": { "description": "Where the checkout page sends the payer after payment", "type": "string", "format": "uri" }, "ipn_url": { "description": "Your endpoint for this payment's status changes (IPN). The body is signed with HMAC-SHA256 using the environment's secret key.", "type": "string", "format": "uri" }, "customer": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "maxLength": 20 } } }, "metadata": { "type": "object", "propertyNames": { "type": "string", "maxLength": 40 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "invoice": { "description": "Issue an e-invoice automatically once the payment succeeds", "type": "object", "properties": { "mode": { "description": "draft: stop at the unsigned draft for you to review; publish: create the draft, then send it for approval (sign). Defaults to the connection's default mode.", "type": "string", "enum": [ "draft", "publish" ] }, "template": { "description": "Template and series; defaults to the provider connection's", "type": "object", "properties": { "pattern": { "type": "string", "minLength": 1, "maxLength": 6, "description": "Template (ký hiệu mẫu số), e.g. 1" }, "serial": { "type": "string", "minLength": 6, "maxLength": 6, "description": "Series (ký hiệu), 6 characters, e.g. C26TAT" } }, "required": [ "pattern", "serial" ] }, "buyer": { "type": "object", "properties": { "name": { "description": "Buyer's name (a person)", "type": "string", "maxLength": 200 }, "legal_name": { "description": "Company name, for a business buyer", "type": "string", "maxLength": 400 }, "tax_code": { "type": "string", "pattern": "^[0-9-]{10,14}$" }, "address": { "type": "string", "maxLength": 400 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "maxLength": 20 }, "buyer_code": { "description": "Your own customer code, shown on the invoice", "type": "string", "maxLength": 50 } } }, "items": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "code": { "type": "string", "maxLength": 50 }, "unit": { "type": "string", "maxLength": 50 }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000 }, "unit_price": { "type": "number", "minimum": 0, "maximum": 10000000000000 }, "vat_rate": { "default": 10, "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 5 }, { "type": "number", "const": 8 }, { "type": "number", "const": 10 }, { "type": "number", "const": -1 }, { "type": "number", "const": -2 } ] }, "discount": { "description": "Discount amount for the line, before VAT", "type": "number", "minimum": 0, "maximum": 10000000000000 }, "vat_amount": { "description": "VAT for the line in VND, instead of the line amount × vat_rate rounded: for when the VAT has to match a figure you already have", "type": "integer", "minimum": 0, "maximum": 10000000000000 } }, "required": [ "name", "quantity", "unit_price" ] } }, "payment_method": { "description": "Shown on the invoice, e.g. \"TM/CK\"", "type": "string", "maxLength": 50 }, "note": { "type": "string", "maxLength": 500 }, "send_email": { "description": "Email the issued invoice to the buyer", "type": "boolean" } }, "required": [ "buyer", "items" ] } }, "required": [ "amount" ] }, "InvoiceRequest": { "type": "object", "properties": { "mode": { "description": "draft: stop at the unsigned draft for you to review; publish: create the draft, then send it for approval (sign). Defaults to the connection's default mode.", "type": "string", "enum": [ "draft", "publish" ] }, "template": { "description": "Template and series; defaults to the provider connection's", "type": "object", "properties": { "pattern": { "type": "string", "minLength": 1, "maxLength": 6, "description": "Template (ký hiệu mẫu số), e.g. 1" }, "serial": { "type": "string", "minLength": 6, "maxLength": 6, "description": "Series (ký hiệu), 6 characters, e.g. C26TAT" } }, "required": [ "pattern", "serial" ] }, "buyer": { "type": "object", "properties": { "name": { "description": "Buyer's name (a person)", "type": "string", "maxLength": 200 }, "legal_name": { "description": "Company name, for a business buyer", "type": "string", "maxLength": 400 }, "tax_code": { "type": "string", "pattern": "^[0-9-]{10,14}$" }, "address": { "type": "string", "maxLength": 400 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "maxLength": 20 }, "buyer_code": { "description": "Your own customer code, shown on the invoice", "type": "string", "maxLength": 50 } } }, "items": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "code": { "type": "string", "maxLength": 50 }, "unit": { "type": "string", "maxLength": 50 }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000 }, "unit_price": { "type": "number", "minimum": 0, "maximum": 10000000000000 }, "vat_rate": { "default": 10, "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 5 }, { "type": "number", "const": 8 }, { "type": "number", "const": 10 }, { "type": "number", "const": -1 }, { "type": "number", "const": -2 } ] }, "discount": { "description": "Discount amount for the line, before VAT", "type": "number", "minimum": 0, "maximum": 10000000000000 }, "vat_amount": { "description": "VAT for the line in VND, instead of the line amount × vat_rate rounded: for when the VAT has to match a figure you already have", "type": "integer", "minimum": 0, "maximum": 10000000000000 } }, "required": [ "name", "quantity", "unit_price" ] } }, "payment_method": { "description": "Shown on the invoice, e.g. \"TM/CK\"", "type": "string", "maxLength": 50 }, "note": { "type": "string", "maxLength": 500 }, "send_email": { "description": "Email the issued invoice to the buyer", "type": "boolean" } }, "required": [ "buyer", "items" ] }, "Payment": { "type": "object", "properties": { "object": { "type": "string", "const": "payment" }, "id": { "type": "string" }, "environment": { "type": "string", "enum": [ "development", "production" ] }, "status": { "type": "string", "enum": [ "pending", "paid", "partially_paid", "overpaid", "expired", "canceled" ] }, "amount": { "type": "integer" }, "paid_amount": { "type": "integer" }, "currency": { "type": "string" }, "code": { "type": "string", "description": "Transfer description the payer sends; the VietQR fills it in" }, "description": { "type": [ "string", "null" ] }, "connection_id": { "type": "string" }, "bank": { "type": [ "object", "null" ], "properties": { "bin": { "type": "string" }, "name": { "type": "string" }, "account_number": { "type": "string" }, "account_name": { "type": "string" } } }, "qr": { "type": "object", "properties": { "payload": { "type": "string", "description": "EMVCo VietQR string" }, "image_url": { "type": "string", "format": "uri" } }, "required": [ "payload", "image_url" ] }, "checkout_url": { "type": "string", "format": "uri" }, "return_url": { "type": [ "string", "null" ] }, "ipn_url": { "type": [ "string", "null" ], "description": "Where IPN calls for this payment go" }, "customer": { "type": [ "object", "null" ] }, "metadata": { "type": "object" }, "invoice": { "oneOf": [ { "$ref": "#/components/schemas/PaymentInvoice" }, { "type": "null" } ], "description": "The e-invoice of this payment and where it stands; null when none was asked for" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "canceled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "environment", "status", "amount", "paid_amount", "currency", "code", "connection_id", "qr", "checkout_url", "created_at" ] }, "PaymentInvoice": { "type": "object", "properties": { "requested": { "type": "boolean" }, "mode": { "type": [ "string", "null" ], "enum": [ "draft", "publish", null ] }, "status": { "type": "string", "enum": [ "waiting_for_payment", "creating", "draft", "publishing", "issued", "tax_accepted", "tax_rejected", "canceled", "replaced", "adjusted", "failed", "deleted" ], "description": "waiting_for_payment: not paid yet; creating: the draft is being created at the provider; publishing: sent for approval; failed without an id: no e-invoice provider connected" }, "id": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "series": { "type": [ "string", "null" ] }, "template": { "type": [ "object", "null" ], "properties": { "pattern": { "type": "string" }, "serial": { "type": "string" } } }, "failed_step": { "type": [ "string", "null" ], "description": "The step that failed; POST /einvoices/{id}/retry runs it again" }, "lookup_code": { "type": [ "string", "null" ] }, "tax_authority_code": { "type": [ "string", "null" ] }, "pdf_url": { "type": [ "string", "null" ] }, "sync_state": { "type": [ "string", "null" ], "enum": [ "in_sync", "pending_push", "conflict", null ] }, "issued_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } }, "required": [ "requested", "mode", "status", "id", "number", "series", "template", "failed_step", "lookup_code", "tax_authority_code", "pdf_url", "sync_state", "issued_at", "error" ] }, "Transaction": { "type": "object", "properties": { "object": { "type": "string", "const": "transaction" }, "id": { "type": "string" }, "environment": { "type": "string", "enum": [ "development", "production" ] }, "connection_id": { "type": "string" }, "direction": { "type": "string", "enum": [ "in", "out" ] }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "description": { "type": "string" }, "code": { "type": [ "string", "null" ], "description": "Payment code or your own order code found in the description" }, "reference": { "type": "string", "description": "Bank reference number" }, "counterparty": { "type": "object", "properties": { "account": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "bank": { "type": [ "string", "null" ] } }, "required": [ "account", "name", "bank" ] }, "booked_at": { "type": "string", "format": "date-time" }, "source": { "type": "string", "enum": [ "push", "reconcile", "import", "simulator" ] }, "payment_id": { "type": [ "string", "null" ] }, "match_status": { "type": "string", "enum": [ "matched", "unmatched", "ignored" ] }, "invoice_exempt": { "type": [ "object", "null" ], "description": "Set when the money needs no invoice and is left out of reconciliation", "properties": { "reason": { "type": [ "string", "null" ] }, "by": { "type": [ "string", "null" ] }, "at": { "type": "string", "format": "date-time" } } }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "environment", "connection_id", "direction", "amount", "currency", "description", "code", "reference", "counterparty", "booked_at", "source", "payment_id", "match_status", "invoice_exempt", "created_at" ] }, "ConnectionConfig": { "type": "object", "properties": { "code_prefix": { "default": "HT", "type": "string", "pattern": "^[A-Z]{2,5}$" }, "payment_code_pattern": { "default": null, "description": "Your own order-code format, extracted from every incoming transfer (webhook-only integrations)", "anyOf": [ { "type": "object", "properties": { "prefix": { "type": "string", "pattern": "^[A-Z0-9]{1,10}$" }, "min_length": { "default": 3, "type": "integer", "minimum": 1, "maximum": 30 }, "max_length": { "default": 10, "type": "integer", "minimum": 1, "maximum": 30 }, "charset": { "default": "digits", "type": "string", "enum": [ "digits", "alnum" ] } }, "required": [ "prefix" ] }, { "type": "null" } ] }, "transaction_events": { "default": { "direction": "in", "require_code": false, "min_amount": 0 }, "type": "object", "properties": { "direction": { "default": "in", "type": "string", "enum": [ "in", "all" ] }, "require_code": { "default": false, "description": "Only send transaction.received when a payment code was found", "type": "boolean" }, "min_amount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "reconcile": { "default": true, "description": "Read this account's history from the bank on a schedule, for banks that allow it (ACB). Off: only pushes and statement imports", "type": "boolean" }, "acb": { "default": null, "anyOf": [ { "type": "object", "properties": { "virtual_account_prefix_code": { "type": "string", "pattern": "^[A-Z0-9]{1,3}$", "description": "Đầu số tài khoản định danh ACB cấp cho tài khoản này (String(3); ACB's UAT issues LOC)" }, "virtual_account_number": { "description": "Tài khoản định danh có sẵn tại ACB, dùng lại thay vì mở mới (String(28)). ACB không có API xin lại chấp thuận cho một VA đã mở, nên chấp thuận được lấy qua đăng ký dịch vụ thông báo cho chính VA đó; đặt trường này cũng là dấu hiệu để hủy liên kết không đóng VA của chủ tài khoản", "type": "string", "pattern": "^[A-Z0-9]{1,28}$" }, "notify_only": { "default": false, "description": "Dịch vụ thông báo thường: đăng ký thông báo giao dịch cho chính tài khoản, không mở hay dùng tài khoản định danh nào (5415/5406 không kèm virtualAccountInfo)", "type": "boolean" }, "virtual_account_content": { "type": "string", "maxLength": 100 }, "virtual_account_explain": { "type": "string", "maxLength": 200 }, "beneficiary_name_rule": { "default": null, "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 99 }, { "type": "null" } ] }, "customer_type": { "description": "ACB customerType (String(4)); defaults to PERS for a personal account and ORG for a business one", "type": "string", "maxLength": 4 }, "user": { "description": "Tài khoản ACB ONE của người dùng; ACB bắt buộc khi customerType = ORG", "type": "string", "maxLength": 100 }, "credit_or_debit_real_time": { "description": "Thông báo ghi có/ghi nợ tức thì", "type": "string", "enum": [ "DEBIT", "CREDIT", "ALL", "NONE" ] }, "credit_or_debit_past_day": { "description": "Thông báo danh sách ghi có/ghi nợ cuối ngày", "type": "string", "enum": [ "DEBIT", "CREDIT", "ALL", "NONE" ] }, "user_agreement": { "default": false, "description": "The holder accepted ACB's terms; ACB's own flow asks for this before the registration is sent", "type": "boolean" } }, "required": [ "virtual_account_prefix_code" ] }, { "type": "null" } ] } } }, "CreateBankConnectionRequest": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 40, "description": "\"mbbank\", \"bidv\", \"acb\" or \"pay2s\" in production, \"simulator\" in development" }, "bank_code": { "description": "Which bank the account is at, for a provider that serves several (the development bank, Pay2S): \"BIDV\", \"ACB\", \"MB\"… It only decides the BIN the VietQR carries", "type": "string", "minLength": 1, "maxLength": 20 }, "account_number": { "description": "Required for real banks; the simulator makes one up", "type": "string", "pattern": "^[0-9A-Z]{4,30}$" }, "account_name": { "description": "Account holder name exactly as the bank has it", "type": "string", "minLength": 1, "maxLength": 200 }, "account_type": { "default": "personal", "type": "string", "enum": [ "personal", "business" ] }, "holder_id": { "description": "National ID (personal) or tax code (business) the account was opened with", "type": "string", "minLength": 6, "maxLength": 20 }, "phone": { "description": "ACB: the mobile number the bank holds for this account — it is where the code is sent", "type": "string", "pattern": "^0\\d{9}$" }, "webhook_token": { "description": "Pay2S: the Hook's token for this account (Webhooks → the key in the Token column on Pay2S)", "type": "string", "minLength": 8, "maxLength": 500 }, "label": { "type": "string", "maxLength": 100 }, "config": { "type": "object", "properties": { "code_prefix": { "default": "HT", "type": "string", "pattern": "^[A-Z]{2,5}$" }, "payment_code_pattern": { "default": null, "description": "Your own order-code format, extracted from every incoming transfer (webhook-only integrations)", "anyOf": [ { "type": "object", "properties": { "prefix": { "type": "string", "pattern": "^[A-Z0-9]{1,10}$" }, "min_length": { "default": 3, "type": "integer", "minimum": 1, "maximum": 30 }, "max_length": { "default": 10, "type": "integer", "minimum": 1, "maximum": 30 }, "charset": { "default": "digits", "type": "string", "enum": [ "digits", "alnum" ] } }, "required": [ "prefix" ] }, { "type": "null" } ] }, "transaction_events": { "default": { "direction": "in", "require_code": false, "min_amount": 0 }, "type": "object", "properties": { "direction": { "default": "in", "type": "string", "enum": [ "in", "all" ] }, "require_code": { "default": false, "description": "Only send transaction.received when a payment code was found", "type": "boolean" }, "min_amount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "reconcile": { "default": true, "description": "Read this account's history from the bank on a schedule, for banks that allow it (ACB). Off: only pushes and statement imports", "type": "boolean" }, "acb": { "default": null, "anyOf": [ { "type": "object", "properties": { "virtual_account_prefix_code": { "type": "string", "pattern": "^[A-Z0-9]{1,3}$", "description": "Đầu số tài khoản định danh ACB cấp cho tài khoản này (String(3); ACB's UAT issues LOC)" }, "virtual_account_number": { "description": "Tài khoản định danh có sẵn tại ACB, dùng lại thay vì mở mới (String(28)). ACB không có API xin lại chấp thuận cho một VA đã mở, nên chấp thuận được lấy qua đăng ký dịch vụ thông báo cho chính VA đó; đặt trường này cũng là dấu hiệu để hủy liên kết không đóng VA của chủ tài khoản", "type": "string", "pattern": "^[A-Z0-9]{1,28}$" }, "notify_only": { "default": false, "description": "Dịch vụ thông báo thường: đăng ký thông báo giao dịch cho chính tài khoản, không mở hay dùng tài khoản định danh nào (5415/5406 không kèm virtualAccountInfo)", "type": "boolean" }, "virtual_account_content": { "type": "string", "maxLength": 100 }, "virtual_account_explain": { "type": "string", "maxLength": 200 }, "beneficiary_name_rule": { "default": null, "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 99 }, { "type": "null" } ] }, "customer_type": { "description": "ACB customerType (String(4)); defaults to PERS for a personal account and ORG for a business one", "type": "string", "maxLength": 4 }, "user": { "description": "Tài khoản ACB ONE của người dùng; ACB bắt buộc khi customerType = ORG", "type": "string", "maxLength": 100 }, "credit_or_debit_real_time": { "description": "Thông báo ghi có/ghi nợ tức thì", "type": "string", "enum": [ "DEBIT", "CREDIT", "ALL", "NONE" ] }, "credit_or_debit_past_day": { "description": "Thông báo danh sách ghi có/ghi nợ cuối ngày", "type": "string", "enum": [ "DEBIT", "CREDIT", "ALL", "NONE" ] }, "user_agreement": { "default": false, "description": "The holder accepted ACB's terms; ACB's own flow asks for this before the registration is sent", "type": "boolean" } }, "required": [ "virtual_account_prefix_code" ] }, { "type": "null" } ] } } } }, "required": [ "provider" ] }, "UpdateBankConnectionRequest": { "type": "object", "properties": { "label": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "config": { "type": "object", "properties": { "code_prefix": { "default": "HT", "type": "string", "pattern": "^[A-Z]{2,5}$" }, "payment_code_pattern": { "default": null, "description": "Your own order-code format, extracted from every incoming transfer (webhook-only integrations)", "anyOf": [ { "type": "object", "properties": { "prefix": { "type": "string", "pattern": "^[A-Z0-9]{1,10}$" }, "min_length": { "default": 3, "type": "integer", "minimum": 1, "maximum": 30 }, "max_length": { "default": 10, "type": "integer", "minimum": 1, "maximum": 30 }, "charset": { "default": "digits", "type": "string", "enum": [ "digits", "alnum" ] } }, "required": [ "prefix" ] }, { "type": "null" } ] }, "transaction_events": { "default": { "direction": "in", "require_code": false, "min_amount": 0 }, "type": "object", "properties": { "direction": { "default": "in", "type": "string", "enum": [ "in", "all" ] }, "require_code": { "default": false, "description": "Only send transaction.received when a payment code was found", "type": "boolean" }, "min_amount": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "reconcile": { "default": true, "description": "Read this account's history from the bank on a schedule, for banks that allow it (ACB). Off: only pushes and statement imports", "type": "boolean" }, "acb": { "default": null, "anyOf": [ { "type": "object", "properties": { "virtual_account_prefix_code": { "type": "string", "pattern": "^[A-Z0-9]{1,3}$", "description": "Đầu số tài khoản định danh ACB cấp cho tài khoản này (String(3); ACB's UAT issues LOC)" }, "virtual_account_number": { "description": "Tài khoản định danh có sẵn tại ACB, dùng lại thay vì mở mới (String(28)). ACB không có API xin lại chấp thuận cho một VA đã mở, nên chấp thuận được lấy qua đăng ký dịch vụ thông báo cho chính VA đó; đặt trường này cũng là dấu hiệu để hủy liên kết không đóng VA của chủ tài khoản", "type": "string", "pattern": "^[A-Z0-9]{1,28}$" }, "notify_only": { "default": false, "description": "Dịch vụ thông báo thường: đăng ký thông báo giao dịch cho chính tài khoản, không mở hay dùng tài khoản định danh nào (5415/5406 không kèm virtualAccountInfo)", "type": "boolean" }, "virtual_account_content": { "type": "string", "maxLength": 100 }, "virtual_account_explain": { "type": "string", "maxLength": 200 }, "beneficiary_name_rule": { "default": null, "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 99 }, { "type": "null" } ] }, "customer_type": { "description": "ACB customerType (String(4)); defaults to PERS for a personal account and ORG for a business one", "type": "string", "maxLength": 4 }, "user": { "description": "Tài khoản ACB ONE của người dùng; ACB bắt buộc khi customerType = ORG", "type": "string", "maxLength": 100 }, "credit_or_debit_real_time": { "description": "Thông báo ghi có/ghi nợ tức thì", "type": "string", "enum": [ "DEBIT", "CREDIT", "ALL", "NONE" ] }, "credit_or_debit_past_day": { "description": "Thông báo danh sách ghi có/ghi nợ cuối ngày", "type": "string", "enum": [ "DEBIT", "CREDIT", "ALL", "NONE" ] }, "user_agreement": { "default": false, "description": "The holder accepted ACB's terms; ACB's own flow asks for this before the registration is sent", "type": "boolean" } }, "required": [ "virtual_account_prefix_code" ] }, { "type": "null" } ] } } } } }, "ConfirmOtpRequest": { "type": "object", "properties": { "otp": { "type": "string", "pattern": "^[0-9]{4,8}$" } }, "required": [ "otp" ] }, "LinkChallenge": { "type": "object", "properties": { "id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "delivery": { "type": "string", "enum": [ "sms_otp" ] } }, "required": [ "id", "expires_at", "delivery" ] }, "AcbNotificationSettingsRequest": { "type": "object", "properties": { "credit_or_debit_real_time": { "type": "string", "enum": [ "DEBIT", "CREDIT", "ALL", "NONE" ], "description": "Thông báo ghi có/ghi nợ tức thì (mặc định ALL)" }, "credit_or_debit_past_day": { "type": "string", "enum": [ "DEBIT", "CREDIT", "ALL", "NONE" ], "description": "Thông báo danh sách ghi có/ghi nợ cuối ngày (mặc định NONE)" }, "on_virtual_account": { "type": "boolean", "description": "Register against the virtual account rather than the main account" } }, "required": [] }, "AcbNotificationChallenge": { "type": "object", "properties": { "object": { "type": "string", "const": "acb_notification_challenge" }, "id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "delivery": { "type": "string", "enum": [ "sms_otp" ] }, "authorization_type": { "type": "string", "description": "ACB's authorizationType, e.g. SMS" } }, "required": [ "object", "id", "expires_at", "delivery", "authorization_type" ] }, "AcbNotificationConfirmed": { "type": "object", "properties": { "object": { "type": "string", "const": "acb_notification" }, "connection_id": { "type": "string" }, "request_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "object", "connection_id", "request_id", "status" ] }, "AcbNotification": { "type": "object", "properties": { "object": { "type": "string", "const": "acb_notification" }, "connection_id": { "type": "string" }, "data": { "type": "object", "description": "ACB's responseData for 7030, field names as ACB writes them", "additionalProperties": true } }, "required": [ "object", "connection_id", "data" ] }, "AcbNotifications": { "type": "object", "properties": { "object": { "type": "string", "const": "acb_notifications" }, "data": { "type": "object", "description": "ACB's responseData for 5337: notificationInfos and pagination", "additionalProperties": true } }, "required": [ "object", "data" ] }, "AcbVirtualAccounts": { "type": "object", "properties": { "object": { "type": "string", "const": "acb_virtual_accounts" }, "connection_id": { "type": "string" }, "account_number": { "type": "string" }, "data": { "type": "object", "description": "ACB's responseData for 5340", "additionalProperties": true } }, "required": [ "object", "data" ] }, "BankConnection": { "type": "object", "properties": { "object": { "type": "string", "const": "bank_connection" }, "id": { "type": "string" }, "environment": { "type": "string", "enum": [ "development", "production" ] }, "provider": { "type": "string" }, "bank": { "type": "object", "properties": { "bin": { "type": "string" }, "name": { "type": "string" } }, "required": [ "bin", "name" ] }, "account_number": { "type": "string" }, "account_name": { "type": "string" }, "account_type": { "type": "string", "enum": [ "personal", "business" ] }, "provider_ref": { "type": [ "string", "null" ], "description": "What the bank calls this link on its side — for ACB, the virtual account payers transfer into" }, "status": { "type": "string", "enum": [ "pending_otp", "active", "needs_reauth", "revoked", "error" ] }, "label": { "type": [ "string", "null" ] }, "config": { "$ref": "#/components/schemas/ConnectionConfig" }, "capabilities": { "type": [ "object", "null" ] }, "last_transaction_at": { "type": [ "string", "null" ], "format": "date-time" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "challenge": { "oneOf": [ { "$ref": "#/components/schemas/LinkChallenge" }, { "type": "null" } ], "description": "Present while a code is awaited" } }, "required": [ "object", "id", "environment", "provider", "account_number", "account_name", "status", "created_at" ] }, "IpnDelivery": { "type": "object", "properties": { "object": { "type": "string", "const": "ipn_delivery" }, "id": { "type": "string" }, "payment_id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed", "exhausted" ] }, "attempt": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ] }, "response_ms": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "payment_id", "event_type", "url", "status", "attempt", "created_at" ] }, "SimulateTransferRequest": { "type": "object", "properties": { "payment_id": { "description": "Pay this payment: fills connection, amount and code", "type": "string" }, "connection_id": { "type": "string" }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000000000 }, "content": { "description": "Transfer description as the bank would report it", "type": "string", "maxLength": 200 }, "direction": { "default": "in", "type": "string", "enum": [ "in", "out" ] }, "reference": { "description": "Bank reference number; reuse one to simulate a duplicate push", "type": "string", "maxLength": 64 }, "counterparty_name": { "type": "string", "maxLength": 200 } } }, "SimulatedTransfer": { "type": "object", "properties": { "object": { "type": "string", "const": "simulated_transfer" }, "reference": { "type": "string" }, "amount": { "type": "integer" }, "direction": { "type": "string" }, "description": { "type": "string" }, "connection_id": { "type": "string" }, "duplicate": { "type": "boolean" } }, "required": [ "object", "reference", "amount", "direction", "description", "connection_id", "duplicate" ] }, "MarkPaidRequest": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 500 }, "amount": { "description": "Amount received; defaults to the payment amount", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } }, "StatementImportRequest": { "type": "object", "properties": { "connection_id": { "type": "string" }, "filename": { "default": "statement.csv", "type": "string", "maxLength": 200 }, "content": { "type": "string", "minLength": 1, "maxLength": 5000000, "description": "CSV: reference,booked_at,direction,amount,description[,counterparty_account,counterparty_name]" } }, "required": [ "connection_id", "content" ] }, "StatementImport": { "type": "object", "properties": { "object": { "type": "string", "const": "statement_import" }, "id": { "type": "string" }, "connection_id": { "type": "string" }, "filename": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "done", "failed" ] }, "rows": { "type": "integer" }, "processed_rows": { "type": "integer" }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "connection_id", "filename", "status", "rows", "processed_rows", "error", "created_at", "completed_at" ] }, "VietQr": { "type": "object", "properties": { "object": { "type": "string", "const": "vietqr" }, "payload": { "type": "string" }, "connection_id": { "type": "string" }, "bank": { "type": "object", "properties": { "bin": { "type": "string" }, "account_number": { "type": "string" }, "account_name": { "type": "string" } }, "required": [ "bin", "account_number", "account_name" ] }, "amount": { "type": [ "integer", "null" ] }, "content": { "type": [ "string", "null" ] } }, "required": [ "object", "payload", "connection_id", "bank", "amount", "content" ] }, "Checkout": { "type": "object", "properties": { "object": { "type": "string", "const": "checkout" }, "id": { "type": "string" }, "environment": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "integer" }, "paid_amount": { "type": "integer" }, "currency": { "type": "string" }, "code": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "merchant": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "bank": { "type": [ "object", "null" ] }, "qr": { "type": "object", "properties": { "payload": { "type": "string" }, "image_url": { "type": "string" } }, "required": [ "payload", "image_url" ] }, "return_url": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "invoice": { "type": [ "object", "null" ], "description": "requested, status, number, series, lookup_code, pdf_url" } }, "required": [ "object", "id", "environment", "status", "amount", "paid_amount", "currency", "code", "description", "merchant", "bank", "qr", "return_url", "expires_at", "paid_at", "invoice" ] }, "CheckEinvoiceConnectionRequest": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 40, "description": "\"matbao\" (GET /einvoices/providers lists what can be connected)" }, "tax_code": { "description": "Seller tax code the provider account logs in with (Mắt Bão MST, e.g. 0302712571-999)", "type": "string", "minLength": 10, "maxLength": 20 }, "username": { "description": "Provider API user (Mắt Bão TDNhap)", "type": "string", "minLength": 1, "maxLength": 200 }, "password": { "description": "Provider API password (Mắt Bão MKhau)", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "provider" ] }, "EinvoiceTemplate": { "type": "object", "properties": { "pattern": { "type": "string" }, "serial": { "type": "string" }, "name": { "type": "string" }, "remaining": { "type": [ "integer", "null" ] } }, "required": [ "pattern", "serial", "name" ] }, "EinvoiceConnectionCheck": { "type": "object", "properties": { "object": { "type": "string", "const": "einvoice_connection_check" }, "ok": { "type": "boolean" }, "provider": { "type": "string" }, "seller_tax_code": { "type": "string" }, "seller_name": { "type": "string" }, "templates": { "type": "array", "items": { "$ref": "#/components/schemas/EinvoiceTemplate" } } }, "required": [ "object", "ok", "provider", "templates" ] }, "EinvoiceProvider": { "type": "object", "properties": { "object": { "type": "string", "const": "einvoice_provider" }, "id": { "type": "string" }, "name": { "type": "string" }, "credential_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "secret": { "type": "boolean" } }, "required": [ "name", "label", "placeholder", "secret" ] } }, "capabilities": { "type": "object" } }, "required": [ "object", "id", "name", "credential_fields" ] }, "CreateEinvoiceConnectionRequest": { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1, "maxLength": 40, "description": "\"matbao\" (GET /einvoices/providers lists what can be connected)" }, "tax_code": { "description": "Seller tax code the provider account logs in with (Mắt Bão MST, e.g. 0302712571-999)", "type": "string", "minLength": 10, "maxLength": 20 }, "username": { "description": "Provider API user (Mắt Bão TDNhap)", "type": "string", "minLength": 1, "maxLength": 200 }, "password": { "description": "Provider API password (Mắt Bão MKhau)", "type": "string", "minLength": 1, "maxLength": 200 }, "pattern": { "type": "string", "minLength": 1, "maxLength": 6, "description": "Default template for new invoices; must be one of the account's (see POST /einvoices/connections/check)" }, "serial": { "type": "string", "minLength": 6, "maxLength": 6, "description": "Series (ký hiệu), 6 characters, e.g. C26TAT" }, "default_mode": { "default": "draft", "type": "string", "enum": [ "draft", "publish" ] }, "is_default": { "description": "Make it the default provider. The first one always is.", "type": "boolean" }, "import_external": { "default": false, "description": "Also bring in invoices created directly on the provider's site", "type": "boolean" }, "auto_invoice": { "default": false, "description": "Issue an invoice for every paid payment, also one created without an invoice block", "type": "boolean" }, "auto_invoice_vat_rate": { "default": 0, "description": "VAT rate of those invoices: 0, 5, 8, 10, -1 (not subject, KCT) or -2 (not declared, KKKNT)", "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 5 }, { "type": "number", "const": 8 }, { "type": "number", "const": 10 }, { "type": "number", "const": -1 }, { "type": "number", "const": -2 } ] }, "label": { "type": "string", "maxLength": 100 } }, "required": [ "provider", "pattern", "serial" ] }, "UpdateEinvoiceConnectionRequest": { "type": "object", "properties": { "default_mode": { "type": "string", "enum": [ "draft", "publish" ] }, "is_default": { "type": "boolean" }, "import_external": { "type": "boolean" }, "auto_invoice": { "type": "boolean" }, "auto_invoice_vat_rate": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 5 }, { "type": "number", "const": 8 }, { "type": "number", "const": 10 }, { "type": "number", "const": -1 }, { "type": "number", "const": -2 } ] }, "label": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "pattern": { "type": "string", "minLength": 1, "maxLength": 6, "description": "Template (ký hiệu mẫu số), e.g. 1" }, "serial": { "type": "string", "minLength": 6, "maxLength": 6, "description": "Series (ký hiệu), 6 characters, e.g. C26TAT" }, "tax_code": { "type": "string", "minLength": 10, "maxLength": 20 }, "username": { "type": "string", "minLength": 1, "maxLength": 200 }, "password": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "EinvoiceConnection": { "type": "object", "properties": { "object": { "type": "string", "const": "einvoice_connection" }, "id": { "type": "string" }, "environment": { "type": "string", "enum": [ "development", "production" ] }, "provider": { "type": "string" }, "provider_name": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "seller_tax_code": { "type": "string" }, "seller_name": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "template": { "type": "object", "properties": { "pattern": { "type": "string" }, "serial": { "type": "string" } }, "required": [ "pattern", "serial" ] }, "default_mode": { "type": "string", "enum": [ "draft", "publish" ] }, "is_default": { "type": "boolean" }, "import_external": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "needs_reauth", "disabled" ], "description": "disabled: unlinked" }, "capabilities": { "type": [ "object", "null" ] }, "callback_url": { "type": [ "string", "null" ], "description": "Give this URL to the provider for status callbacks" }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_sync_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "environment", "provider", "seller_tax_code", "template", "default_mode", "is_default", "status", "created_at" ] }, "CreateEinvoiceRequest": { "type": "object", "properties": { "mode": { "description": "draft: stop after creating the draft; publish: create the draft, then send it for approval (sign). Both go through the queue.", "type": "string", "enum": [ "draft", "publish" ] }, "connection_id": { "description": "Provider connection; defaults to the default one", "type": "string" }, "template": { "description": "Template and series; defaults to the connection's", "type": "object", "properties": { "pattern": { "type": "string", "minLength": 1, "maxLength": 6, "description": "Template (ký hiệu mẫu số), e.g. 1" }, "serial": { "type": "string", "minLength": 6, "maxLength": 6, "description": "Series (ký hiệu), 6 characters, e.g. C26TAT" } }, "required": [ "pattern", "serial" ] }, "payment_id": { "description": "Link to a payment (one invoice per payment)", "type": "string" }, "transaction_id": { "description": "Link to a bank transaction (webhook-only integrations)", "type": "string" }, "buyer": { "type": "object", "properties": { "name": { "description": "Buyer's name (a person)", "type": "string", "maxLength": 200 }, "legal_name": { "description": "Company name, for a business buyer", "type": "string", "maxLength": 400 }, "tax_code": { "type": "string", "pattern": "^[0-9-]{10,14}$" }, "address": { "type": "string", "maxLength": 400 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "maxLength": 20 }, "buyer_code": { "description": "Your own customer code, shown on the invoice", "type": "string", "maxLength": 50 } } }, "items": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "code": { "type": "string", "maxLength": 50 }, "unit": { "type": "string", "maxLength": 50 }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000 }, "unit_price": { "type": "number", "minimum": 0, "maximum": 10000000000000 }, "vat_rate": { "default": 10, "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 5 }, { "type": "number", "const": 8 }, { "type": "number", "const": 10 }, { "type": "number", "const": -1 }, { "type": "number", "const": -2 } ] }, "discount": { "description": "Discount amount for the line, before VAT", "type": "number", "minimum": 0, "maximum": 10000000000000 }, "vat_amount": { "description": "VAT for the line in VND, instead of the line amount × vat_rate rounded: for when the VAT has to match a figure you already have", "type": "integer", "minimum": 0, "maximum": 10000000000000 } }, "required": [ "name", "quantity", "unit_price" ] } }, "payment_method": { "type": "string", "maxLength": 50 }, "note": { "type": "string", "maxLength": 500 }, "send_email": { "type": "boolean" } }, "required": [ "buyer", "items" ] }, "UpdateEinvoiceRequest": { "type": "object", "properties": { "buyer": { "type": "object", "properties": { "name": { "description": "Buyer's name (a person)", "type": "string", "maxLength": 200 }, "legal_name": { "description": "Company name, for a business buyer", "type": "string", "maxLength": 400 }, "tax_code": { "type": "string", "pattern": "^[0-9-]{10,14}$" }, "address": { "type": "string", "maxLength": 400 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "maxLength": 20 }, "buyer_code": { "description": "Your own customer code, shown on the invoice", "type": "string", "maxLength": 50 } } }, "items": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "code": { "type": "string", "maxLength": 50 }, "unit": { "type": "string", "maxLength": 50 }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000 }, "unit_price": { "type": "number", "minimum": 0, "maximum": 10000000000000 }, "vat_rate": { "default": 10, "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 5 }, { "type": "number", "const": 8 }, { "type": "number", "const": 10 }, { "type": "number", "const": -1 }, { "type": "number", "const": -2 } ] }, "discount": { "description": "Discount amount for the line, before VAT", "type": "number", "minimum": 0, "maximum": 10000000000000 }, "vat_amount": { "description": "VAT for the line in VND, instead of the line amount × vat_rate rounded: for when the VAT has to match a figure you already have", "type": "integer", "minimum": 0, "maximum": 10000000000000 } }, "required": [ "name", "quantity", "unit_price" ] } }, "payment_method": { "type": "string", "maxLength": 50 }, "note": { "type": "string", "maxLength": 500 } } }, "ReplaceEinvoiceRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "buyer": { "type": "object", "properties": { "name": { "description": "Buyer's name (a person)", "type": "string", "maxLength": 200 }, "legal_name": { "description": "Company name, for a business buyer", "type": "string", "maxLength": 400 }, "tax_code": { "type": "string", "pattern": "^[0-9-]{10,14}$" }, "address": { "type": "string", "maxLength": 400 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "maxLength": 20 }, "buyer_code": { "description": "Your own customer code, shown on the invoice", "type": "string", "maxLength": 50 } } }, "items": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 500 }, "code": { "type": "string", "maxLength": 50 }, "unit": { "type": "string", "maxLength": 50 }, "quantity": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000 }, "unit_price": { "type": "number", "minimum": 0, "maximum": 10000000000000 }, "vat_rate": { "default": 10, "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 5 }, { "type": "number", "const": 8 }, { "type": "number", "const": 10 }, { "type": "number", "const": -1 }, { "type": "number", "const": -2 } ] }, "discount": { "description": "Discount amount for the line, before VAT", "type": "number", "minimum": 0, "maximum": 10000000000000 }, "vat_amount": { "description": "VAT for the line in VND, instead of the line amount × vat_rate rounded: for when the VAT has to match a figure you already have", "type": "integer", "minimum": 0, "maximum": 10000000000000 } }, "required": [ "name", "quantity", "unit_price" ] } }, "payment_method": { "type": "string", "maxLength": 50 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "reason", "buyer", "items" ] }, "ResolveConflictRequest": { "type": "object", "properties": { "keep": { "type": "string", "enum": [ "hatang", "provider" ] } }, "required": [ "keep" ] }, "Einvoice": { "type": "object", "properties": { "object": { "type": "string", "const": "einvoice" }, "id": { "type": "string" }, "environment": { "type": "string", "enum": [ "development", "production" ] }, "connection_id": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "payment_id": { "type": [ "string", "null" ] }, "transaction_id": { "type": [ "string", "null" ] }, "origin": { "type": "string", "enum": [ "hatang", "provider" ] }, "mode": { "type": "string", "enum": [ "draft", "publish" ] }, "status": { "type": "string", "enum": [ "creating", "draft", "publishing", "issued", "tax_accepted", "tax_rejected", "canceled", "replaced", "adjusted", "failed", "deleted" ] }, "sync_state": { "type": "string", "enum": [ "in_sync", "pending_push", "conflict" ], "description": "pending_push: a change is on its way to the provider; conflict: edited on both sides" }, "version": { "type": "integer" }, "buyer": { "type": "object" }, "items": { "type": "array", "items": { "type": "object" } }, "totals": { "type": "object", "properties": { "subtotal": { "type": "integer" }, "vat": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "subtotal", "vat", "total" ] }, "currency": { "type": "string" }, "payment_method": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "template": { "type": "object", "properties": { "pattern": { "type": "string" }, "serial": { "type": "string" } }, "required": [ "pattern", "serial" ] }, "reference": { "type": "string", "description": "Our reference at the provider (Mắt Bão MTChieu / lookup code)" }, "provider_invoice_id": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "series": { "type": [ "string", "null" ] }, "lookup_code": { "type": [ "string", "null" ] }, "tax_authority_code": { "type": [ "string", "null" ] }, "pdf_url": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ], "format": "date-time" }, "related_invoice_id": { "type": [ "string", "null" ] }, "relation": { "type": [ "string", "null" ] }, "conflict": { "type": [ "object", "null" ] }, "error": { "type": [ "string", "null" ] }, "failed_step": { "type": [ "string", "null" ], "enum": [ "create_draft", "update_draft", "publish", "delete_draft", null ], "description": "The step that failed; POST /einvoices/{id}/retry runs it again" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "environment", "connection_id", "origin", "mode", "status", "sync_state", "buyer", "items", "totals", "reference", "created_at" ] }, "EinvoiceHistoryEntry": { "type": "object", "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": "string" }, "source": { "type": "string", "enum": [ "hatang", "provider_sync", "provider_webhook", "manual" ] }, "detail": { "type": [ "object", "null" ] }, "at": { "type": "string", "format": "date-time" } }, "required": [ "from", "to", "source", "detail", "at" ] }, "EinvoiceSync": { "type": "object", "properties": { "object": { "type": "string", "const": "einvoice_sync" }, "connection_id": { "type": "string" }, "queued": { "type": "boolean" } }, "required": [ "object", "connection_id", "queued" ] }, "InvoiceExemptRequest": { "type": "object", "properties": { "reason": { "description": "Why this money needs no invoice, e.g. a refund or a transfer between your own accounts", "type": "string", "maxLength": 500 } } }, "ReconciliationAmount": { "type": "object", "properties": { "count": { "type": "integer" }, "amount": { "type": "integer" } }, "required": [ "count", "amount" ] }, "ReconciliationItem": { "type": "object", "properties": { "id": { "type": "string" }, "connection_id": { "type": "string" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "description": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "counterparty_name": { "type": [ "string", "null" ] }, "payment_id": { "type": [ "string", "null" ] }, "booked_at": { "type": "string", "format": "date-time" }, "invoice_exempt": { "type": [ "object", "null" ] } }, "required": [ "id", "connection_id", "amount", "currency", "description", "code", "counterparty_name", "payment_id", "booked_at", "invoice_exempt" ] }, "InvoiceReconciliation": { "type": "object", "properties": { "object": { "type": "string", "const": "invoice_reconciliation" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "totals": { "type": "object", "properties": { "money_in": { "$ref": "#/components/schemas/ReconciliationAmount" }, "invoiced": { "$ref": "#/components/schemas/ReconciliationAmount" }, "missing": { "$ref": "#/components/schemas/ReconciliationAmount" }, "exempt": { "$ref": "#/components/schemas/ReconciliationAmount" } }, "required": [ "money_in", "invoiced", "missing", "exempt" ] }, "days": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "description": "YYYY-MM-DD, Vietnam time" }, "count": { "type": "integer" }, "money_in": { "type": "integer" }, "invoiced": { "type": "integer" }, "missing": { "type": "integer" }, "exempt": { "type": "integer" }, "missing_count": { "type": "integer" } }, "required": [ "day", "count", "money_in", "invoiced", "missing", "exempt", "missing_count" ] } }, "missing": { "type": "array", "description": "Money in without an invoice in force (newest first, at most 200)", "items": { "$ref": "#/components/schemas/ReconciliationItem" } }, "exempt": { "type": "array", "description": "Money in taken out of reconciliation", "items": { "$ref": "#/components/schemas/ReconciliationItem" } } }, "required": [ "object", "from", "to", "totals", "days", "missing", "exempt" ] }, "EmailEventData": { "type": "object", "properties": { "email_id": { "type": "string", "description": "The email's id, as returned by `POST /emails`" }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "bounce": { "type": "object", "properties": { "message": { "type": "string" }, "subType": { "type": "string" }, "type": { "type": "string", "enum": [ "Permanent", "Transient", "Undetermined" ] } }, "required": [ "message", "subType", "type" ] }, "click": { "type": "object", "properties": { "link": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "ipAddress": { "type": "string" }, "userAgent": { "type": "string" } }, "required": [ "link", "timestamp" ] }, "open": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "ipAddress": { "type": "string" }, "userAgent": { "type": "string" } }, "required": [ "timestamp" ] }, "failed": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] } }, "required": [ "email_id", "from", "to", "subject", "created_at" ], "description": "An outbound email. `bounce`, `click`, `open` and `failed` are present only on the matching event." }, "ReceivedEmailEventData": { "type": "object", "properties": { "email_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "from": { "type": "string", "description": "`Name
` when the sender gave a name" }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "message_id": { "type": [ "string", "null" ] }, "subject": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "content_disposition": { "type": "string", "enum": [ "inline", "attachment" ] }, "content_id": { "type": [ "string", "null" ] }, "size": { "type": "integer" } }, "required": [ "id", "filename", "content_type", "content_disposition", "content_id", "size" ] } } }, "required": [ "email_id", "created_at", "from", "to", "cc", "bcc", "message_id", "subject", "attachments" ] }, "ContactEventData": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "unsubscribed": { "type": "boolean" }, "properties": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "email", "first_name", "last_name", "unsubscribed", "properties", "created_at", "updated_at" ] }, "FlowWebhookEventData": { "description": "Sent by a flow's or a workflow's **Webhook** step. Flows send `flow_id`, `flow_name`, `step`, `vars` and the visitor; workflows send `name`, `source: \"workflow\"` and the facts of the run.", "type": "object", "properties": { "conversation_id": { "type": "string" }, "visitor_id": { "type": "string" }, "flow_id": { "type": "string" }, "flow_name": { "type": "string" }, "step": { "type": "string" }, "vars": { "type": "object", "additionalProperties": true }, "visitor": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name", "email", "phone" ] }, "name": { "type": "string" }, "source": { "type": "string", "const": "workflow" } }, "required": [ "conversation_id", "visitor_id" ], "additionalProperties": true }, "CampaignLeadEventData": { "description": "A visitor left their details in a campaign form or the widget's lead form. Form fields are added as extra properties.", "type": "object", "properties": { "campaign_id": { "type": "string" }, "campaign": { "type": "string" }, "conversation_id": { "type": "string" }, "visitor_id": { "type": "string" }, "customer_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "campaign", "conversation_id", "visitor_id" ], "additionalProperties": true }, "InvoiceFailedEventData": { "description": "Either the e-invoice that failed, or (when no provider is connected) `{object, payment_id, status, error}`.", "oneOf": [ { "$ref": "#/components/schemas/Einvoice" }, { "type": "object", "properties": { "object": { "type": "string", "const": "einvoice" }, "payment_id": { "type": "string" }, "status": { "type": "string", "const": "failed" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "object", "payment_id", "status", "error" ] } ] } } }, "webhooks": { "email.sent": { "post": { "operationId": "webhook_email_sent", "tags": [ "Email events" ], "summary": "email.sent", "security": [], "description": "The email was accepted by the sending infrastructure.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "email.sent" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/EmailEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "email.delivered": { "post": { "operationId": "webhook_email_delivered", "tags": [ "Email events" ], "summary": "email.delivered", "security": [], "description": "The recipient's mail server accepted the email.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "email.delivered" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/EmailEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "email.delivery_delayed": { "post": { "operationId": "webhook_email_delivery_delayed", "tags": [ "Email events" ], "summary": "email.delivery_delayed", "security": [], "description": "Delivery is being retried (for example the recipient's server is temporarily refusing mail).\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "email.delivery_delayed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/EmailEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "email.bounced": { "post": { "operationId": "webhook_email_bounced", "tags": [ "Email events" ], "summary": "email.bounced", "security": [], "description": "The email bounced. `data.bounce.type` is `Permanent` (the address is suppressed) or `Transient`.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "email.bounced" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/EmailEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "email.complained": { "post": { "operationId": "webhook_email_complained", "tags": [ "Email events" ], "summary": "email.complained", "security": [], "description": "The recipient marked the email as spam. The address is suppressed.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "email.complained" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/EmailEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "email.opened": { "post": { "operationId": "webhook_email_opened", "tags": [ "Email events" ], "summary": "email.opened", "security": [], "description": "The recipient opened the email (open tracking on). Fired once per open.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "email.opened" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/EmailEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "email.clicked": { "post": { "operationId": "webhook_email_clicked", "tags": [ "Email events" ], "summary": "email.clicked", "security": [], "description": "The recipient clicked a tracked link. `data.click.link` is the original URL.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "email.clicked" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/EmailEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "email.failed": { "post": { "operationId": "webhook_email_failed", "tags": [ "Email events" ], "summary": "email.failed", "security": [], "description": "The email could not be sent. `data.failed.reason` says why.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "email.failed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/EmailEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "email.received": { "post": { "operationId": "webhook_email_received", "tags": [ "Email events" ], "summary": "email.received", "security": [], "description": "An email arrived at one of your receiving domains. Fetch the body and attachments with the Receiving API.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "email.received" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ReceivedEmailEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "contact.created": { "post": { "operationId": "webhook_contact_created", "tags": [ "Email events" ], "summary": "contact.created", "security": [], "description": "A contact was added (API, dashboard, import or CRM sync).\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "contact.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ContactEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "contact.updated": { "post": { "operationId": "webhook_contact_updated", "tags": [ "Email events" ], "summary": "contact.updated", "security": [], "description": "A contact's name, properties or subscription changed.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "contact.updated" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ContactEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "contact.deleted": { "post": { "operationId": "webhook_contact_deleted", "tags": [ "Email events" ], "summary": "contact.deleted", "security": [], "description": "A contact was deleted.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "contact.deleted" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ContactEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "domain.created": { "post": { "operationId": "webhook_domain_created", "tags": [ "Email events" ], "summary": "domain.created", "security": [], "description": "A sending domain was added.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "domain.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Domain" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "domain.updated": { "post": { "operationId": "webhook_domain_updated", "tags": [ "Email events" ], "summary": "domain.updated", "security": [], "description": "A domain changed, including its verification status.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "domain.updated" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Domain" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "domain.deleted": { "post": { "operationId": "webhook_domain_deleted", "tags": [ "Email events" ], "summary": "domain.deleted", "security": [], "description": "A domain was removed.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "domain.deleted" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Domain" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.conversation.created": { "post": { "operationId": "webhook_chat_conversation_created", "tags": [ "Support events" ], "summary": "chat.conversation.created", "security": [], "description": "A new conversation started on any channel.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.conversation.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatConversation" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.conversation.assigned": { "post": { "operationId": "webhook_chat_conversation_assigned", "tags": [ "Support events" ], "summary": "chat.conversation.assigned", "security": [], "description": "A conversation was assigned (or unassigned).\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.conversation.assigned" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatConversation" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.conversation.resolved": { "post": { "operationId": "webhook_chat_conversation_resolved", "tags": [ "Support events" ], "summary": "chat.conversation.resolved", "security": [], "description": "A conversation was marked resolved.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.conversation.resolved" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatConversation" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.conversation.closed": { "post": { "operationId": "webhook_chat_conversation_closed", "tags": [ "Support events" ], "summary": "chat.conversation.closed", "security": [], "description": "A conversation was closed.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.conversation.closed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatConversation" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.conversation.reopened": { "post": { "operationId": "webhook_chat_conversation_reopened", "tags": [ "Support events" ], "summary": "chat.conversation.reopened", "security": [], "description": "A resolved or closed conversation was reopened.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.conversation.reopened" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatConversation" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.conversation.handoff": { "post": { "operationId": "webhook_chat_conversation_handoff", "tags": [ "Support events" ], "summary": "chat.conversation.handoff", "security": [], "description": "The AI assistant handed the conversation to your team.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.conversation.handoff" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "allOf": [ { "$ref": "#/components/schemas/ChatConversation" }, { "type": "object", "properties": { "reason": { "type": "string" }, "summary": { "type": [ "string", "null" ] } }, "required": [ "reason" ] } ] } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.conversation.tagged": { "post": { "operationId": "webhook_chat_conversation_tagged", "tags": [ "Support events" ], "summary": "chat.conversation.tagged", "security": [], "description": "A tag was added to a conversation; one event per added tag.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.conversation.tagged" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "allOf": [ { "$ref": "#/components/schemas/ChatConversation" }, { "type": "object", "properties": { "tag": { "type": "string" } }, "required": [ "tag" ] } ] } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.message.created": { "post": { "operationId": "webhook_chat_message_created", "tags": [ "Support events" ], "summary": "chat.message.created", "security": [], "description": "A public message was posted by the customer, an agent, the AI assistant or a flow. Internal notes do not fire it.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.message.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "allOf": [ { "$ref": "#/components/schemas/ChatTimelineItem" }, { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/ChatConversation" } }, "required": [ "conversation" ] } ] } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.visitor.identified": { "post": { "operationId": "webhook_chat_visitor_identified", "tags": [ "Support events" ], "summary": "chat.visitor.identified", "security": [], "description": "A visitor was identified (`identify` from the widget or an SDK).\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.visitor.identified" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatVisitor" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.order.created": { "post": { "operationId": "webhook_chat_order_created", "tags": [ "Support events" ], "summary": "chat.order.created", "security": [], "description": "An order was created from the inbox or the API.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.order.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatOrder" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.order.updated": { "post": { "operationId": "webhook_chat_order_updated", "tags": [ "Support events" ], "summary": "chat.order.updated", "security": [], "description": "An order changed (status, items, shipping).\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.order.updated" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatOrder" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.order.paid": { "post": { "operationId": "webhook_chat_order_paid", "tags": [ "Support events" ], "summary": "chat.order.paid", "security": [], "description": "An order was paid.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.order.paid" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatOrder" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.flow.webhook": { "post": { "operationId": "webhook_chat_flow_webhook", "tags": [ "Support events" ], "summary": "chat.flow.webhook", "security": [], "description": "A flow or workflow reached a Webhook step.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.flow.webhook" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/FlowWebhookEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.campaign.lead": { "post": { "operationId": "webhook_chat_campaign_lead", "tags": [ "Support events" ], "summary": "chat.campaign.lead", "security": [], "description": "A visitor submitted a lead form.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.campaign.lead" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/CampaignLeadEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.ticket.created": { "post": { "operationId": "webhook_chat_ticket_created", "tags": [ "Support events" ], "summary": "chat.ticket.created", "security": [], "description": "A support ticket was created.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.ticket.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatTicket" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.ticket.updated": { "post": { "operationId": "webhook_chat_ticket_updated", "tags": [ "Support events" ], "summary": "chat.ticket.updated", "security": [], "description": "A ticket changed.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.ticket.updated" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatTicket" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.ticket.resolved": { "post": { "operationId": "webhook_chat_ticket_resolved", "tags": [ "Support events" ], "summary": "chat.ticket.resolved", "security": [], "description": "A ticket was resolved.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.ticket.resolved" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatTicket" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.ticket.breached": { "post": { "operationId": "webhook_chat_ticket_breached", "tags": [ "Support events" ], "summary": "chat.ticket.breached", "security": [], "description": "A ticket missed an SLA target. `clock` says which one.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.ticket.breached" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "allOf": [ { "$ref": "#/components/schemas/ChatTicket" }, { "type": "object", "properties": { "clock": { "type": "string", "enum": [ "first_response", "resolve" ] } }, "required": [ "clock" ] } ] } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.rating.created": { "post": { "operationId": "webhook_chat_rating_created", "tags": [ "Support events" ], "summary": "chat.rating.created", "security": [], "description": "A customer rated a conversation (CSAT).\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.rating.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatRating" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.zns.sent": { "post": { "operationId": "webhook_chat_zns_sent", "tags": [ "Support events" ], "summary": "chat.zns.sent", "security": [], "description": "A Zalo ZNS message was delivered to Zalo.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.zns.sent" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatZnsMessage" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "chat.zns.failed": { "post": { "operationId": "webhook_chat_zns_failed", "tags": [ "Support events" ], "summary": "chat.zns.failed", "security": [], "description": "A Zalo ZNS message failed. `error` has the reason.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "chat.zns.failed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ChatZnsMessage" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "payment.created": { "post": { "operationId": "webhook_payment_created", "tags": [ "Payments events" ], "summary": "payment.created", "security": [], "description": "A payment request was created.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "payment.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "payment.succeeded": { "post": { "operationId": "webhook_payment_succeeded", "tags": [ "Payments events" ], "summary": "payment.succeeded", "security": [], "description": "The full amount arrived.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "payment.succeeded" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "payment.partially_paid": { "post": { "operationId": "webhook_payment_partially_paid", "tags": [ "Payments events" ], "summary": "payment.partially_paid", "security": [], "description": "Less than the full amount arrived.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "payment.partially_paid" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "payment.overpaid": { "post": { "operationId": "webhook_payment_overpaid", "tags": [ "Payments events" ], "summary": "payment.overpaid", "security": [], "description": "More than the requested amount arrived.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "payment.overpaid" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "payment.expired": { "post": { "operationId": "webhook_payment_expired", "tags": [ "Payments events" ], "summary": "payment.expired", "security": [], "description": "The payment expired before it was paid.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "payment.expired" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "payment.canceled": { "post": { "operationId": "webhook_payment_canceled", "tags": [ "Payments events" ], "summary": "payment.canceled", "security": [], "description": "The payment was canceled.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "payment.canceled" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Payment" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "transaction.received": { "post": { "operationId": "webhook_transaction_received", "tags": [ "Payments events" ], "summary": "transaction.received", "security": [], "description": "Money arrived in a linked bank account (matched or not).\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "transaction.received" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "merchant_code": { "type": [ "string", "null" ] } }, "required": [] } ] } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "bank_connection.activated": { "post": { "operationId": "webhook_bank_connection_activated", "tags": [ "Payments events" ], "summary": "bank_connection.activated", "security": [], "description": "A bank account was linked and confirmed.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "bank_connection.activated" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/BankConnection" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "bank_connection.revoked": { "post": { "operationId": "webhook_bank_connection_revoked", "tags": [ "Payments events" ], "summary": "bank_connection.revoked", "security": [], "description": "A bank link was removed.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "bank_connection.revoked" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/BankConnection" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "bank_connection.needs_reauth": { "post": { "operationId": "webhook_bank_connection_needs_reauth", "tags": [ "Payments events" ], "summary": "bank_connection.needs_reauth", "security": [], "description": "The bank needs the account holder to confirm the link again.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "bank_connection.needs_reauth" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/BankConnection" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "invoice.draft_created": { "post": { "operationId": "webhook_invoice_draft_created", "tags": [ "Payments events" ], "summary": "invoice.draft_created", "security": [], "description": "A draft e-invoice was created.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.draft_created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Einvoice" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "invoice.draft_updated": { "post": { "operationId": "webhook_invoice_draft_updated", "tags": [ "Payments events" ], "summary": "invoice.draft_updated", "security": [], "description": "A draft e-invoice changed.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.draft_updated" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Einvoice" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "invoice.draft_deleted": { "post": { "operationId": "webhook_invoice_draft_deleted", "tags": [ "Payments events" ], "summary": "invoice.draft_deleted", "security": [], "description": "A draft e-invoice was deleted.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.draft_deleted" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Einvoice" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "invoice.issued": { "post": { "operationId": "webhook_invoice_issued", "tags": [ "Payments events" ], "summary": "invoice.issued", "security": [], "description": "An e-invoice was issued by the provider.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.issued" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Einvoice" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "invoice.tax_accepted": { "post": { "operationId": "webhook_invoice_tax_accepted", "tags": [ "Payments events" ], "summary": "invoice.tax_accepted", "security": [], "description": "The tax authority accepted the e-invoice.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.tax_accepted" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Einvoice" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "invoice.tax_rejected": { "post": { "operationId": "webhook_invoice_tax_rejected", "tags": [ "Payments events" ], "summary": "invoice.tax_rejected", "security": [], "description": "The tax authority rejected the e-invoice.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.tax_rejected" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Einvoice" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "invoice.canceled": { "post": { "operationId": "webhook_invoice_canceled", "tags": [ "Payments events" ], "summary": "invoice.canceled", "security": [], "description": "An e-invoice was canceled.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.canceled" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Einvoice" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "invoice.replaced": { "post": { "operationId": "webhook_invoice_replaced", "tags": [ "Payments events" ], "summary": "invoice.replaced", "security": [], "description": "An e-invoice was replaced by a new one.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.replaced" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Einvoice" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "invoice.adjusted": { "post": { "operationId": "webhook_invoice_adjusted", "tags": [ "Payments events" ], "summary": "invoice.adjusted", "security": [], "description": "An adjustment invoice was issued.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.adjusted" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Einvoice" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "invoice.failed": { "post": { "operationId": "webhook_invoice_failed", "tags": [ "Payments events" ], "summary": "invoice.failed", "security": [], "description": "Issuing an e-invoice failed.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.failed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/InvoiceFailedEventData" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } }, "invoice.conflict": { "post": { "operationId": "webhook_invoice_conflict", "tags": [ "Payments events" ], "summary": "invoice.conflict", "security": [], "description": "The invoice changed on the provider's side and conflicts with Ha Tang's copy.\n\nDelivered as a signed `POST` to your endpoint with `svix-id`, `svix-timestamp` and `svix-signature` headers (also sent as `webhook-*`). Answer with any 2xx within 15 seconds; failures are retried.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "invoice.conflict" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Einvoice" } }, "required": [ "type", "created_at", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx status. Anything else (or no answer) is retried." } } } } } }