{"openapi":"3.1.0","info":{"title":"API Platform API","version":"2026-10-01","summary":"Contacts, WhatsApp templates, inbox, webhooks and reports.","description":"The API Platform REST API. JSON in and out, snake_case fields, cursor pagination and `application/problem+json` errors with a stable `code`.\n\nPin a version with the `Api-Version` header; a key uses the version current when it was made.","termsOfService":"https://copilot.wa-api.cloud","contact":{"url":"https://copilot.wa-api.cloud"}},"servers":[{"url":"https://mcp.wa-api.cloud/v1","description":"API Platform API"}],"security":[{"api_key":[]}],"tags":[{"name":"contacts","description":"The people you talk to: find, create, update and import them.","x-displayName":"Contacts"},{"name":"tags","description":"Label contacts so you can find, filter and message them.","x-displayName":"Tags"},{"name":"groups","description":"Audiences for broadcasts and filters: create groups and add or remove contacts.","x-displayName":"Contact groups"},{"name":"custom-fields","description":"The extra fields every contact can carry, such as a loyalty tier or an order count.","x-displayName":"Custom fields"},{"name":"messages","description":"Send messages and read them: approved WhatsApp templates to one contact, free-form messages in a conversation while its reply window is open, and a conversation's message history.","x-displayName":"Messages"},{"name":"templates","description":"Read, check, create and edit your WhatsApp templates.","x-displayName":"Templates"},{"name":"quick-messages","description":"Saved replies your team inserts in the inbox with a short code.","x-displayName":"Quick messages"},{"name":"short-links","description":"WhatsApp click-to-chat links with a QR code that open a chat with your number, message already typed.","x-displayName":"Short links"},{"name":"broadcasts","description":"Read your broadcasts and their delivery numbers, and check whether you can send one.","x-displayName":"Broadcasts"},{"name":"channels","description":"Your connected WhatsApp numbers and other channels.","x-displayName":"Channels"},{"name":"inbox","description":"Find and read conversations (with their reply window), add internal notes and reminders, tag, assign, close and reopen them. Sending and reading messages is under Messages.","x-displayName":"Conversations"},{"name":"webhooks","description":"Get told when things happen: endpoints, subscriptions, deliveries and replays.","x-displayName":"Webhooks"},{"name":"reports","description":"Numbers for dashboards and nightly exports.","x-displayName":"Reports"},{"name":"events","description":"Events we POST to your webhook endpoints.","x-displayName":"Events"}],"paths":{"/channels":{"get":{"operationId":"listChannels","summary":"List channels","description":"Lists the channels connected to your workspace (WhatsApp numbers, Instagram, web chat, …). Use a channel `id` as `channel_id` when sending.","tags":["channels"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"type","in":"query","required":false,"description":"Only this channel type.","schema":{"description":"Only this channel type.","type":"string","enum":["whatsapp","instagram","messenger","web","tiktok","telegram","email","sms"]}},{"name":"search","in":"query","required":false,"description":"Name or number contains.","schema":{"description":"Name or number contains.","type":"string","minLength":1,"maxLength":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of channels.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Workspace channel id — pass it as channelId to any tool (template and Flow tools accept it too)."},"meta_channel_id":{"description":"The same channel in the WhatsApp/Meta service; null when not linked.","type":["string","null"]},"name":{"type":["string","null"]},"type":{"description":"whatsapp, instagram, messenger, web, …","type":["string","null"]},"identifier":{"description":"Business phone number, username or page shown for this channel.","type":["string","null"]},"is_default":{"type":"boolean"},"status":{"type":"string","enum":["connected","disconnected","inactive","unknown"]},"web_surface":{"description":"web / ios / android for web chat channels.","type":["string","null"]},"meta_phone_number_id":{"description":"Meta phone_number_id (WhatsApp) — an id, not a secret.","type":["string","null"]},"payment_configuration":{"type":["string","null"]},"quality_rating":{"description":"Meta quality rating; null = not exposed by the platform yet.","type":["string","null"]}},"required":["id","meta_channel_id","name","type","identifier","is_default","status","web_surface","meta_phone_number_id","payment_configuration","quality_rating"],"additionalProperties":false}},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"warnings":{"type":"array","items":{"type":"string"}},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","warnings","next_cursor"]},"examples":{"whatsapp":{"summary":"WhatsApp numbers","value":{"data":[{"id":"301","name":"Main WhatsApp","type":"whatsapp","identifier":"+15555550100","is_default":true,"status":"connected","quality_rating":"GREEN","meta_channel_id":null,"web_surface":null,"meta_phone_number_id":null,"payment_configuration":null}],"next_cursor":null,"total":1,"warnings":[]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"workspace_channels","x-platform-ops-path":"/ops/workspace_channels","x-platform-group":"channels","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"whatsapp","summary":"WhatsApp numbers","path":{},"query":{"type":"whatsapp"},"response":{"status":200,"body":{"data":[{"id":"301","name":"Main WhatsApp","type":"whatsapp","identifier":"+15555550100","is_default":true,"status":"connected","quality_rating":"GREEN","meta_channel_id":null,"web_surface":null,"meta_phone_number_id":null,"payment_configuration":null}],"next_cursor":null,"total":1,"warnings":[]}}}]}},"/contacts":{"get":{"operationId":"listContacts","summary":"List contacts","description":"Finds contacts in your workspace, newest first. Filter by text, tags, groups, starred or do-not-disturb. For custom fields, dates, assigned staff, broadcasts and saved filters use **Search contacts** (`POST /contacts/search`).\n\nUse `detail=full` to include email, tags and groups on every row.","tags":["contacts"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"query","in":"query","required":false,"description":"Name or phone contains this text.","schema":{"description":"Name or phone contains this text.","type":"string","minLength":1,"maxLength":100}},{"name":"group_ids","in":"query","required":false,"description":"Contacts in ANY of these groups.","schema":{"description":"Contacts in ANY of these groups.","maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Group id (numeric id)."}},"style":"form","explode":true},{"name":"tag_ids","in":"query","required":false,"description":"Contacts with ANY of these tags (repeat the parameter).","schema":{"description":"Contacts with ANY of these tags (repeat the parameter).","maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Tag id (numeric id)."}},"style":"form","explode":true,"x-platform-picker":"tags"},{"name":"starred","in":"query","required":false,"description":"`true` = starred contacts only.","schema":{"description":"`true` = starred contacts only.","type":"boolean"}},{"name":"dnd","in":"query","required":false,"description":"`true` = do-not-disturb on; `false` = can receive broadcasts.","schema":{"description":"`true` = do-not-disturb on; `false` = can receive broadcasts.","type":"boolean"}},{"name":"not_in_any_group","in":"query","required":false,"description":"`true` = contacts in no group.","schema":{"description":"`true` = contacts in no group.","type":"boolean"}},{"name":"detail","in":"query","required":false,"description":"`summary` (default) or `full` (adds email, tags and groups).","schema":{"default":"summary","description":"`summary` (default) or `full` (adds email, tags and groups).","type":"string","enum":["summary","full"]}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of contacts.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"phone":{"description":"As the platform shows it to this staff member: E.164 digits, or masked (e.g. \"*******12345\") when the workspace hides numbers from agents. Never unmasked here.","type":["string","null"]},"phone_masked":{"type":"boolean"},"whatsapp_user_id":{"type":["string","null"]},"dnd":{"type":"boolean","description":"Do-not-disturb: the contact receives no broadcasts/marketing."},"starred":{"description":"null only when it could not be read this time (`unavailable` includes profile_extras).","type":["boolean","null"]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"email":{"type":["string","null"]},"web_visitor_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"attributes":{"description":"Every custom field value this staff member may see (manager-only fields are hidden from agents; deleted fields never appear), at most 100. Text values longer than 2000 characters are clipped.","type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The custom field key (as in `GET /v1/custom-fields`)."},"label":{"description":"The field label shown in the panel.","type":["string","null"]},"type":{"description":"text, textarea, number, int, float, decimal, email, phone, url, select, radio, multiselect, checkbox, boolean, date or datetime.","type":["string","null"]},"value":{"description":"The value as the panel shows it: text; checkbox/boolean \"Yes\"/\"No\"; date \"YYYY-MM-DD\"; datetime \"YYYY-MM-DD HH:MM:SS\" (UTC); multiselect \"a, b\"; int/float numbers; decimal a string with 8 decimals."},"display":{"description":"value as text.","type":["string","null"]},"typed_value":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]},{"type":"null"}],"description":"value typed by the field type: number/int/float/decimal → number; checkbox/boolean → true/false; date → \"YYYY-MM-DD\"; datetime → ISO-8601 UTC; multiselect → array of the chosen values; select/radio/text/… → string. null when empty or unreadable."}},"required":["key","label","type","value","display","typed_value"],"additionalProperties":false}},"conversations":{"description":"Newest first (at most 10), a timeline summary; read messages with the inbox tools.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel_id":{"type":["string","null"]},"state":{"type":["string","null"]},"assigned":{"type":"boolean"},"assigned_staff_id":{"type":["string","null"]},"created_at":{"type":["string","null"]},"last_activity_at":{"type":["string","null"]}},"required":["id","channel_id","state","assigned","assigned_staff_id","created_at","last_activity_at"],"additionalProperties":false}},"last_activity_at":{"description":"Latest conversation activity (from the conversation list).","type":["string","null"]},"unavailable":{"description":"Present only when part of the contact could not be read this time (retry later for it): profile_extras = starred, createdAt, updatedAt and webVisitorId are null because they are unknown, not empty; conversations = the timeline (and lastActivityAt) is empty because it could not be read, not because there are none.","type":"array","items":{"type":"string","enum":["profile_extras","conversations"]}}},"required":["id","name","phone","phone_masked","whatsapp_user_id","dnd","starred","created_at","updated_at"],"additionalProperties":false}},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Contacts matching the filters (all pages); with filter / savedFilterId / sort only on the first page."},"approximate":{"description":"true when total is an estimate (advanced path).","type":["boolean","null"]},"resolved_dates":{"description":"Relative or local dates in filter and the absolute instants they were run with.","type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"input":{"type":"string"},"value":{"type":"string"}},"required":["path","input","value"],"additionalProperties":false}},"warnings":{"description":"Filter conditions that may not mean what they look like: {path, message}.","type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","next_cursor"]},"examples":{"vip":{"summary":"VIP contacts with full detail","value":{"data":[{"id":"48213","name":"Jane Doe","phone":"+15555550123","phone_masked":false,"email":"jane@example.com","dnd":false,"starred":false,"tags":[{"id":"17","name":"vip"}],"groups":[{"id":"5","name":"Newsletter"}],"created_at":"2026-09-20T08:14:03Z","updated_at":"2026-09-23T16:40:11Z","whatsapp_user_id":null}],"next_cursor":"eyJ2IjoxLCJwIjoyfQ.c2ln","total":1}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_search_contacts","x-platform-ops-path":"/ops/crm_search_contacts","x-platform-group":"contacts","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"vip","summary":"VIP contacts with full detail","path":{},"query":{"tag_ids":["17"],"detail":"full","limit":2},"response":{"status":200,"body":{"data":[{"id":"48213","name":"Jane Doe","phone":"+15555550123","phone_masked":false,"email":"jane@example.com","dnd":false,"starred":false,"tags":[{"id":"17","name":"vip"}],"groups":[{"id":"5","name":"Newsletter"}],"created_at":"2026-09-20T08:14:03Z","updated_at":"2026-09-23T16:40:11Z","whatsapp_user_id":null}],"next_cursor":"eyJ2IjoxLCJwIjoyfQ.c2ln","total":1}}}]},"post":{"operationId":"upsertContact","summary":"Create or update a contact","description":"Creates a contact, or updates the one that already has this phone number — so calling it twice is safe. Groups and tags you pass are **added**; existing ones are kept.\n\nThis is the call to use when syncing from a shop or CRM.","tags":["contacts"],"security":[{"api_key":["crm:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","minLength":3,"maxLength":32,"description":"International format with country code, e.g. `+15555550123`. Local numbers starting with 0 are refused."},"name":{"description":"Full name.","type":"string","minLength":1,"maxLength":255},"email":{"description":"Email address (stored in the `email` custom field).","type":"string","maxLength":255},"attributes":{"description":"Custom field values by key. `null` or `\"\"` clears a value. Unknown keys are refused with the list of valid ones.","type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":255},"additionalProperties":{"anyOf":[{"type":"string","maxLength":10000},{"type":"number"},{"type":"boolean"},{"maxItems":100,"type":"array","items":{"type":"string","maxLength":255}},{"type":"null"}]}},"group_ids":{"description":"Group ids.","maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Group id (numeric id)."}},"tags":{"description":"Tag names or ids. Names that do not exist yet are created.","maxItems":20,"type":"array","items":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}]},"x-platform-picker":"tags"}},"required":["phone"],"additionalProperties":false},"examples":{"shop":{"summary":"A new customer from your shop","value":{"phone":"+15555550123","name":"Jane Doe","email":"jane@example.com","tags":["shopify","vip"],"attributes":{"order_count":4}}}}}}},"responses":{"200":{"description":"The contact, and whether it was created or updated.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"action":{"type":"string","enum":["created","updated","unchanged"]},"contact":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"phone":{"description":"As the platform shows it to this staff member: E.164 digits, or masked (e.g. \"*******12345\") when the workspace hides numbers from agents. Never unmasked here.","type":["string","null"]},"phone_masked":{"type":"boolean"},"whatsapp_user_id":{"type":["string","null"]},"dnd":{"type":"boolean","description":"Do-not-disturb: the contact receives no broadcasts/marketing."},"starred":{"description":"null only when it could not be read this time (`unavailable` includes profile_extras).","type":["boolean","null"]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"email":{"type":["string","null"]},"web_visitor_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"attributes":{"description":"Every custom field value this staff member may see (manager-only fields are hidden from agents; deleted fields never appear), at most 100. Text values longer than 2000 characters are clipped.","type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The custom field key (as in `GET /v1/custom-fields`)."},"label":{"description":"The field label shown in the panel.","type":["string","null"]},"type":{"description":"text, textarea, number, int, float, decimal, email, phone, url, select, radio, multiselect, checkbox, boolean, date or datetime.","type":["string","null"]},"value":{"description":"The value as the panel shows it: text; checkbox/boolean \"Yes\"/\"No\"; date \"YYYY-MM-DD\"; datetime \"YYYY-MM-DD HH:MM:SS\" (UTC); multiselect \"a, b\"; int/float numbers; decimal a string with 8 decimals."},"display":{"description":"value as text.","type":["string","null"]},"typed_value":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]},{"type":"null"}],"description":"value typed by the field type: number/int/float/decimal → number; checkbox/boolean → true/false; date → \"YYYY-MM-DD\"; datetime → ISO-8601 UTC; multiselect → array of the chosen values; select/radio/text/… → string. null when empty or unreadable."}},"required":["key","label","type","value","display","typed_value"],"additionalProperties":false}},"conversations":{"description":"Newest first (at most 10), a timeline summary; read messages with the inbox tools.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel_id":{"type":["string","null"]},"state":{"type":["string","null"]},"assigned":{"type":"boolean"},"assigned_staff_id":{"type":["string","null"]},"created_at":{"type":["string","null"]},"last_activity_at":{"type":["string","null"]}},"required":["id","channel_id","state","assigned","assigned_staff_id","created_at","last_activity_at"],"additionalProperties":false}},"last_activity_at":{"description":"Latest conversation activity (from the conversation list).","type":["string","null"]},"unavailable":{"description":"Present only when part of the contact could not be read this time (retry later for it): profile_extras = starred, createdAt, updatedAt and webVisitorId are null because they are unknown, not empty; conversations = the timeline (and lastActivityAt) is empty because it could not be read, not because there are none.","type":"array","items":{"type":"string","enum":["profile_extras","conversations"]}}},"required":["id","name","phone","phone_masked","whatsapp_user_id","dnd","starred","created_at","updated_at"],"additionalProperties":false},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","action","contact"]},"examples":{"shop":{"summary":"A new customer from your shop","value":{"id":"48213","action":"created","contact":{"id":"48213","name":"Jane Doe","phone":"+15555550123","phone_masked":false,"email":"jane@example.com","dnd":false,"starred":false,"tags":[{"id":"17","name":"vip"}],"groups":[{"id":"5","name":"Newsletter"}],"created_at":"2026-09-20T08:14:03Z","updated_at":"2026-09-23T16:40:11Z","whatsapp_user_id":null}}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Too many other contacts' numbers contain this one to find the existing contact exactly (`reason: lookup_incomplete`): nothing is created, so no duplicate; update the contact by id instead.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Too many other contacts' numbers contain this one to find the existing contact exactly (`reason: lookup_incomplete`): nothing is created, so no duplicate; update the contact by id instead.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Too many other contacts' numbers contain this one to find the existing contact exactly (`reason: lookup_incomplete`): nothing is created, so no duplicate; update the contact by id instead.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: Your plan contact limit is reached (`reason: plan_contact_limit`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"Your plan contact limit is reached (`reason: plan_contact_limit`).","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"Your plan contact limit is reached (`reason: plan_contact_limit`).","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"502":{"description":"`upstream_error`: The contact service answered unexpectedly. Retry with the same Idempotency-Key.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_error":{"summary":"The contact service answered unexpectedly. Retry with the same Idempotency-Key.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_error","title":"A connected service answered unexpectedly","status":502,"detail":"The contact service answered unexpectedly. Retry with the same Idempotency-Key.","code":"upstream_error","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_upsert_contact","x-platform-ops-path":"/ops/crm_upsert_contact","x-platform-group":"contacts","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Update the contact again, or delete it if it was just created.","x-platform-events":["contact.created/1","contact.updated/1"],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Too many other contacts' numbers contain this one to find the existing contact exactly (`reason: lookup_incomplete`): nothing is created, so no duplicate; update the contact by id instead."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"Your plan contact limit is reached (`reason: plan_contact_limit`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_error","status":502,"when":"The contact service answered unexpectedly. Retry with the same Idempotency-Key."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"shop","summary":"A new customer from your shop","path":{},"query":{},"body":{"phone":"+15555550123","name":"Jane Doe","email":"jane@example.com","tags":["shopify","vip"],"attributes":{"order_count":4}},"response":{"status":200,"body":{"id":"48213","action":"created","contact":{"id":"48213","name":"Jane Doe","phone":"+15555550123","phone_masked":false,"email":"jane@example.com","dnd":false,"starred":false,"tags":[{"id":"17","name":"vip"}],"groups":[{"id":"5","name":"Newsletter"}],"created_at":"2026-09-20T08:14:03Z","updated_at":"2026-09-23T16:40:11Z","whatsapp_user_id":null}}}}]}},"/contacts/search":{"post":{"operationId":"searchContacts","summary":"Search contacts","description":"Finds contacts with the advanced filter your team uses on the contacts page: any field, custom fields, dates (also relative, like `-7d` or `start_of_month`), groups, assigned staff, conversation tags, broadcasts and saved filters, combined with `and`, `or` and `not`.\n\n`filter` keeps the contacts page's own format (camelCase keys such as `phoneNumber`, `attributeName`), so a filter you build here can be saved and opened in the app unchanged. Give `saved_filter_id` to apply a saved filter (with `filter` too, both must match). `total` comes with the first page.","tags":["contacts"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filter":{"description":"The advanced filter: `{field: {operator: value}}` joined with `and` / `or` / `not`. See the filtering guide.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"saved_filter_id":{"description":"Apply a saved contact filter.","anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}]},"sort":{"description":"`{\"field\": \"createdAt\"|\"updatedAt\"|\"name\"|\"phoneNumber\"|\"id\", \"direction\": \"asc\"|\"desc\"}` (default newest first).","type":"object","properties":{"field":{"type":"string","enum":["createdAt","updatedAt","name","phoneNumber","id"],"description":"Sort key."},"direction":{"default":"desc","description":"asc or desc (default desc).","type":"string","enum":["asc","desc"]}},"required":["field"],"additionalProperties":false},"detail":{"default":"summary","description":"`summary` (default) or `full` (adds groups).","type":"string","enum":["summary","full"]},"limit":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100},"cursor":{"description":"The `next_cursor` from the previous page, with the same filter. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},"additionalProperties":false},"examples":{"dubai-recent":{"summary":"Contacts in Dubai added in the last 30 days","value":{"filter":{"and":[{"attributes":{"some":{"attributeName":{"eq":"city"},"stringValue":{"eq":"Dubai"}}}},{"createdAt":{"gte":"-30d"}}]},"limit":2}}}}}},"responses":{"200":{"description":"A page of contacts.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"phone":{"description":"As the platform shows it to this staff member: E.164 digits, or masked (e.g. \"*******12345\") when the workspace hides numbers from agents. Never unmasked here.","type":["string","null"]},"phone_masked":{"type":"boolean"},"whatsapp_user_id":{"type":["string","null"]},"dnd":{"type":"boolean","description":"Do-not-disturb: the contact receives no broadcasts/marketing."},"starred":{"description":"null only when it could not be read this time (`unavailable` includes profile_extras).","type":["boolean","null"]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"email":{"type":["string","null"]},"web_visitor_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"attributes":{"description":"Every custom field value this staff member may see (manager-only fields are hidden from agents; deleted fields never appear), at most 100. Text values longer than 2000 characters are clipped.","type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The custom field key (as in `GET /v1/custom-fields`)."},"label":{"description":"The field label shown in the panel.","type":["string","null"]},"type":{"description":"text, textarea, number, int, float, decimal, email, phone, url, select, radio, multiselect, checkbox, boolean, date or datetime.","type":["string","null"]},"value":{"description":"The value as the panel shows it: text; checkbox/boolean \"Yes\"/\"No\"; date \"YYYY-MM-DD\"; datetime \"YYYY-MM-DD HH:MM:SS\" (UTC); multiselect \"a, b\"; int/float numbers; decimal a string with 8 decimals."},"display":{"description":"value as text.","type":["string","null"]},"typed_value":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]},{"type":"null"}],"description":"value typed by the field type: number/int/float/decimal → number; checkbox/boolean → true/false; date → \"YYYY-MM-DD\"; datetime → ISO-8601 UTC; multiselect → array of the chosen values; select/radio/text/… → string. null when empty or unreadable."}},"required":["key","label","type","value","display","typed_value"],"additionalProperties":false}},"conversations":{"description":"Newest first (at most 10), a timeline summary; read messages with the inbox tools.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel_id":{"type":["string","null"]},"state":{"type":["string","null"]},"assigned":{"type":"boolean"},"assigned_staff_id":{"type":["string","null"]},"created_at":{"type":["string","null"]},"last_activity_at":{"type":["string","null"]}},"required":["id","channel_id","state","assigned","assigned_staff_id","created_at","last_activity_at"],"additionalProperties":false}},"last_activity_at":{"description":"Latest conversation activity (from the conversation list).","type":["string","null"]},"unavailable":{"description":"Present only when part of the contact could not be read this time (retry later for it): profile_extras = starred, createdAt, updatedAt and webVisitorId are null because they are unknown, not empty; conversations = the timeline (and lastActivityAt) is empty because it could not be read, not because there are none.","type":"array","items":{"type":"string","enum":["profile_extras","conversations"]}}},"required":["id","name","phone","phone_masked","whatsapp_user_id","dnd","starred","created_at","updated_at"],"additionalProperties":false}},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Contacts matching the filters (all pages); with filter / savedFilterId / sort only on the first page."},"approximate":{"description":"true when total is an estimate (advanced path).","type":["boolean","null"]},"resolved_dates":{"description":"Relative or local dates in filter and the absolute instants they were run with.","type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"input":{"type":"string"},"value":{"type":"string"}},"required":["path","input","value"],"additionalProperties":false}},"warnings":{"description":"Filter conditions that may not mean what they look like: {path, message}.","type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","next_cursor"]},"examples":{"dubai-recent":{"summary":"Contacts in Dubai added in the last 30 days","value":{"data":[{"id":"48213","name":"Jane Doe","phone":"15555550123","phone_masked":false,"whatsapp_user_id":null,"dnd":false,"starred":false,"created_at":"2026-09-20T08:14:03.000Z","updated_at":"2026-09-23T16:40:11.000Z"}],"next_cursor":null,"total":1,"approximate":false,"resolved_dates":[{"path":"filter.and.1.createdAt.gte","input":"-30d","value":"2026-08-31T08:00:00.000Z"}]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid: each problem names its field and how to fix it. `reason` names the class when there is one: `filter_too_deep`, `filter_too_many_conditions`, `filter_list_too_long`, `filter_string_too_long`, `filter_regex_too_long`, `filter_regex_invalid`, `filter_too_large`, `saved_filter_cycle`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid: each problem names its field and how to fix it. `reason` names the class when there is one: `filter_too_deep`, `filter_too_many_conditions`, `filter_list_too_long`, `filter_string_too_long`, `filter_regex_too_long`, `filter_regex_invalid`, `filter_too_large`, `saved_filter_cycle`.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid: each problem names its field and how to fix it. `reason` names the class when there is one: `filter_too_deep`, `filter_too_many_conditions`, `filter_list_too_long`, `filter_string_too_long`, `filter_regex_too_long`, `filter_regex_invalid`, `filter_too_large`, `saved_filter_cycle`.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The filter or sort compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The filter or sort compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`).","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The filter or sort compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`).","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`).","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`).","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"502":{"description":"`upstream_error`: The contacts service could not run this filter (`reason: filter_failed`), e.g. a regular expression its engine gives up on. Simplify the filter; retrying the same one fails again.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_error":{"summary":"The contacts service could not run this filter (`reason: filter_failed`), e.g. a regular expression its engine gives up on. Simplify the filter; retrying the same one fails again.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_error","title":"A connected service answered unexpectedly","status":502,"detail":"The contacts service could not run this filter (`reason: filter_failed`), e.g. a regular expression its engine gives up on. Simplify the filter; retrying the same one fails again.","code":"upstream_error","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`service_unconfigured`: Advanced filters are switched off on this server (`reason: advanced_filter_disabled`). `upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unconfigured":{"summary":"Advanced filters are switched off on this server (`reason: advanced_filter_disabled`).","value":{"type":"https://dev.wa-api.cloud/errors/service_unconfigured","title":"This feature is not set up here","status":503,"detail":"Advanced filters are switched off on this server (`reason: advanced_filter_disabled`).","code":"service_unconfigured","request_id":"req_01J8ZEXAMPLE0000000000000"}},"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The filter took too long to run (`reason: query_timeout`): narrow it.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The filter took too long to run (`reason: query_timeout`): narrow it.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The filter took too long to run (`reason: query_timeout`): narrow it.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_search_contacts","x-platform-ops-path":"/ops/crm_search_contacts","x-platform-group":"contacts","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid: each problem names its field and how to fix it. `reason` names the class when there is one: `filter_too_deep`, `filter_too_many_conditions`, `filter_list_too_long`, `filter_string_too_long`, `filter_regex_too_long`, `filter_regex_invalid`, `filter_too_large`, `saved_filter_cycle`."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The filter or sort compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`)."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_error","status":502,"when":"The contacts service could not run this filter (`reason: filter_failed`), e.g. a regular expression its engine gives up on. Simplify the filter; retrying the same one fails again."},{"code":"service_unconfigured","status":503,"when":"Advanced filters are switched off on this server (`reason: advanced_filter_disabled`)."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The filter took too long to run (`reason: query_timeout`): narrow it."}],"x-platform-examples":[{"name":"dubai-recent","summary":"Contacts in Dubai added in the last 30 days","path":{},"query":{},"body":{"filter":{"and":[{"attributes":{"some":{"attributeName":{"eq":"city"},"stringValue":{"eq":"Dubai"}}}},{"createdAt":{"gte":"-30d"}}]},"limit":2},"response":{"status":200,"body":{"data":[{"id":"48213","name":"Jane Doe","phone":"15555550123","phone_masked":false,"whatsapp_user_id":null,"dnd":false,"starred":false,"created_at":"2026-09-20T08:14:03.000Z","updated_at":"2026-09-23T16:40:11.000Z"}],"next_cursor":null,"total":1,"approximate":false,"resolved_dates":[{"path":"filter.and.1.createdAt.gte","input":"-30d","value":"2026-08-31T08:00:00.000Z"}]}}}]}},"/contacts/{contact_id}":{"get":{"operationId":"getContact","summary":"Get a contact","description":"Returns one contact with every custom field value, tags, groups and when they last talked to you.\n\nIf part of the contact cannot be read right now, the answer still comes back with `unavailable` listing what is missing: `profile_extras` means `starred`, `created_at`, `updated_at` and `web_visitor_id` are `null` because they are unknown; `conversations` means the timeline is empty because it could not be read. Retry later for those parts.","tags":["contacts"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"contact_id","in":"path","required":true,"description":"The contact id.","schema":{"description":"Contact id (from `GET /v1/contacts`).","anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}]},"x-platform-picker":"contacts"},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The contact.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"phone":{"description":"As the platform shows it to this staff member: E.164 digits, or masked (e.g. \"*******12345\") when the workspace hides numbers from agents. Never unmasked here.","type":["string","null"]},"phone_masked":{"type":"boolean"},"whatsapp_user_id":{"type":["string","null"]},"dnd":{"type":"boolean","description":"Do-not-disturb: the contact receives no broadcasts/marketing."},"starred":{"description":"null only when it could not be read this time (`unavailable` includes profile_extras).","type":["boolean","null"]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"email":{"type":["string","null"]},"web_visitor_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"attributes":{"description":"Every custom field value this staff member may see (manager-only fields are hidden from agents; deleted fields never appear), at most 100. Text values longer than 2000 characters are clipped.","type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The custom field key (as in `GET /v1/custom-fields`)."},"label":{"description":"The field label shown in the panel.","type":["string","null"]},"type":{"description":"text, textarea, number, int, float, decimal, email, phone, url, select, radio, multiselect, checkbox, boolean, date or datetime.","type":["string","null"]},"value":{"description":"The value as the panel shows it: text; checkbox/boolean \"Yes\"/\"No\"; date \"YYYY-MM-DD\"; datetime \"YYYY-MM-DD HH:MM:SS\" (UTC); multiselect \"a, b\"; int/float numbers; decimal a string with 8 decimals."},"display":{"description":"value as text.","type":["string","null"]},"typed_value":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]},{"type":"null"}],"description":"value typed by the field type: number/int/float/decimal → number; checkbox/boolean → true/false; date → \"YYYY-MM-DD\"; datetime → ISO-8601 UTC; multiselect → array of the chosen values; select/radio/text/… → string. null when empty or unreadable."}},"required":["key","label","type","value","display","typed_value"],"additionalProperties":false}},"conversations":{"description":"Newest first (at most 10), a timeline summary; read messages with the inbox tools.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel_id":{"type":["string","null"]},"state":{"type":["string","null"]},"assigned":{"type":"boolean"},"assigned_staff_id":{"type":["string","null"]},"created_at":{"type":["string","null"]},"last_activity_at":{"type":["string","null"]}},"required":["id","channel_id","state","assigned","assigned_staff_id","created_at","last_activity_at"],"additionalProperties":false}},"last_activity_at":{"description":"Latest conversation activity (from the conversation list).","type":["string","null"]},"unavailable":{"description":"Present only when part of the contact could not be read this time (retry later for it): profile_extras = starred, createdAt, updatedAt and webVisitorId are null because they are unknown, not empty; conversations = the timeline (and lastActivityAt) is empty because it could not be read, not because there are none.","type":"array","items":{"type":"string","enum":["profile_extras","conversations"]}}},"required":["id","name","phone","phone_masked","whatsapp_user_id","dnd","starred","created_at","updated_at"]},"examples":{"basic":{"summary":"Read one contact","value":{"id":"48213","name":"Jane Doe","phone":"+15555550123","phone_masked":false,"email":"jane@example.com","dnd":false,"starred":false,"tags":[{"id":"17","name":"vip"}],"groups":[{"id":"5","name":"Newsletter"}],"created_at":"2026-09-20T08:14:03Z","updated_at":"2026-09-23T16:40:11Z","attributes":[{"key":"order_count","label":"Orders","type":"number","value":4,"display":"4","typed_value":4}],"last_activity_at":"2026-09-23T16:40:11Z","whatsapp_user_id":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No contact with this id in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No contact with this id in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No contact with this id in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_get_contact","x-platform-ops-path":"/ops/crm_get_contact","x-platform-group":"contacts","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No contact with this id in your workspace."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"basic","summary":"Read one contact","path":{"contact_id":"48213"},"query":{},"response":{"status":200,"body":{"id":"48213","name":"Jane Doe","phone":"+15555550123","phone_masked":false,"email":"jane@example.com","dnd":false,"starred":false,"tags":[{"id":"17","name":"vip"}],"groups":[{"id":"5","name":"Newsletter"}],"created_at":"2026-09-20T08:14:03Z","updated_at":"2026-09-23T16:40:11Z","attributes":[{"key":"order_count","label":"Orders","type":"number","value":4,"display":"4","typed_value":4}],"last_activity_at":"2026-09-23T16:40:11Z","whatsapp_user_id":null}}}]},"patch":{"operationId":"updateContact","summary":"Update a contact","description":"Changes only the fields you pass. The phone number cannot change: create a new contact instead.","tags":["contacts"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"contact_id","in":"path","required":true,"description":"The contact id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Contact id (numeric id)."},"x-platform-picker":"contacts"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Full name.","type":"string","minLength":1,"maxLength":255},"email":{"description":"Email; `\"\"` clears it.","type":"string","maxLength":255},"attributes":{"description":"Custom field values by key. `null` or `\"\"` clears a value. Unknown keys are refused with the list of valid ones.","type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":255},"additionalProperties":{"anyOf":[{"type":"string","maxLength":10000},{"type":"number"},{"type":"boolean"},{"maxItems":100,"type":"array","items":{"type":"string","maxLength":255}},{"type":"null"}]}},"add_to_group_ids":{"description":"Group ids.","maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Group id (numeric id)."}},"remove_from_group_ids":{"description":"Group ids.","maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Group id (numeric id)."}}},"additionalProperties":false},"examples":{"rename":{"summary":"Fix a name and set a custom field","value":{"name":"Jane A. Doe","attributes":{"preferred_language":"en"}}}}}}},"responses":{"200":{"description":"The updated contact.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"action":{"type":"string","enum":["created","updated","unchanged"]},"contact":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"phone":{"description":"As the platform shows it to this staff member: E.164 digits, or masked (e.g. \"*******12345\") when the workspace hides numbers from agents. Never unmasked here.","type":["string","null"]},"phone_masked":{"type":"boolean"},"whatsapp_user_id":{"type":["string","null"]},"dnd":{"type":"boolean","description":"Do-not-disturb: the contact receives no broadcasts/marketing."},"starred":{"description":"null only when it could not be read this time (`unavailable` includes profile_extras).","type":["boolean","null"]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"email":{"type":["string","null"]},"web_visitor_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"attributes":{"description":"Every custom field value this staff member may see (manager-only fields are hidden from agents; deleted fields never appear), at most 100. Text values longer than 2000 characters are clipped.","type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The custom field key (as in `GET /v1/custom-fields`)."},"label":{"description":"The field label shown in the panel.","type":["string","null"]},"type":{"description":"text, textarea, number, int, float, decimal, email, phone, url, select, radio, multiselect, checkbox, boolean, date or datetime.","type":["string","null"]},"value":{"description":"The value as the panel shows it: text; checkbox/boolean \"Yes\"/\"No\"; date \"YYYY-MM-DD\"; datetime \"YYYY-MM-DD HH:MM:SS\" (UTC); multiselect \"a, b\"; int/float numbers; decimal a string with 8 decimals."},"display":{"description":"value as text.","type":["string","null"]},"typed_value":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]},{"type":"null"}],"description":"value typed by the field type: number/int/float/decimal → number; checkbox/boolean → true/false; date → \"YYYY-MM-DD\"; datetime → ISO-8601 UTC; multiselect → array of the chosen values; select/radio/text/… → string. null when empty or unreadable."}},"required":["key","label","type","value","display","typed_value"],"additionalProperties":false}},"conversations":{"description":"Newest first (at most 10), a timeline summary; read messages with the inbox tools.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel_id":{"type":["string","null"]},"state":{"type":["string","null"]},"assigned":{"type":"boolean"},"assigned_staff_id":{"type":["string","null"]},"created_at":{"type":["string","null"]},"last_activity_at":{"type":["string","null"]}},"required":["id","channel_id","state","assigned","assigned_staff_id","created_at","last_activity_at"],"additionalProperties":false}},"last_activity_at":{"description":"Latest conversation activity (from the conversation list).","type":["string","null"]},"unavailable":{"description":"Present only when part of the contact could not be read this time (retry later for it): profile_extras = starred, createdAt, updatedAt and webVisitorId are null because they are unknown, not empty; conversations = the timeline (and lastActivityAt) is empty because it could not be read, not because there are none.","type":"array","items":{"type":"string","enum":["profile_extras","conversations"]}}},"required":["id","name","phone","phone_masked","whatsapp_user_id","dnd","starred","created_at","updated_at"],"additionalProperties":false},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","action","contact"]},"examples":{"rename":{"summary":"Fix a name and set a custom field","value":{"id":"48213","action":"updated","contact":{"id":"48213","name":"Jane A. Doe","phone":"+15555550123","phone_masked":false,"email":"jane@example.com","dnd":false,"starred":false,"tags":[{"id":"17","name":"vip"}],"groups":[{"id":"5","name":"Newsletter"}],"created_at":"2026-09-20T08:14:03Z","updated_at":"2026-09-23T16:40:11Z","whatsapp_user_id":null}}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No contact with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No contact with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No contact with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_update_contact","x-platform-ops-path":"/ops/crm_update_contact","x-platform-group":"contacts","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Send the old values back.","x-platform-events":["contact.updated/1","contact.group.added/1","contact.group.removed/1"],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No contact with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"rename","summary":"Fix a name and set a custom field","path":{"contact_id":"48213"},"query":{},"body":{"name":"Jane A. Doe","attributes":{"preferred_language":"en"}},"response":{"status":200,"body":{"id":"48213","action":"updated","contact":{"id":"48213","name":"Jane A. Doe","phone":"+15555550123","phone_masked":false,"email":"jane@example.com","dnd":false,"starred":false,"tags":[{"id":"17","name":"vip"}],"groups":[{"id":"5","name":"Newsletter"}],"created_at":"2026-09-20T08:14:03Z","updated_at":"2026-09-23T16:40:11Z","whatsapp_user_id":null}}}}]},"delete":{"operationId":"deleteContact","summary":"Delete a contact","description":"Deletes one contact. It disappears from groups, tags and future broadcasts.\n\nRefused when the contact has already received messages, so conversation history is never lost.","tags":["contacts"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"contact_id","in":"path","required":true,"description":"The contact id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Contact id (numeric id)."},"x-platform-picker":"contacts"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"Deleted.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"deleted":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","deleted"]},"examples":{"delete":{"summary":"Delete a test contact","value":{"id":"48213","deleted":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The contact has received messages and is kept for history. `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The contact has received messages and is kept for history.","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The contact has received messages and is kept for history.","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No contact with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No contact with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No contact with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_delete_contact","x-platform-ops-path":"/ops/crm_delete_contact","x-platform-group":"contacts","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":"delete","x-platform-undo":"Cannot be undone. Create the contact again with the same phone number.","x-platform-events":["contact.deleted/1"],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The contact has received messages and is kept for history."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No contact with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"delete","summary":"Delete a test contact","path":{"contact_id":"48213"},"query":{},"response":{"status":200,"body":{"id":"48213","deleted":true}}}]}},"/contacts/lookup":{"get":{"operationId":"lookupContact","summary":"Find a contact by phone","description":"Looks a contact up by phone number instead of id. Use it when your own system only knows the number.\n\nIf part of the contact cannot be read right now, the answer still comes back with `unavailable` listing what is missing: `profile_extras` means `starred`, `created_at`, `updated_at` and `web_visitor_id` are `null` because they are unknown; `conversations` means the timeline is empty because it could not be read. Retry later for those parts.","tags":["contacts"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"phone","in":"query","required":true,"description":"International format, e.g. `+15555550123`.","schema":{"description":"International format, e.g. `+15555550123`.","type":"string","minLength":3,"maxLength":32}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The contact.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"phone":{"description":"As the platform shows it to this staff member: E.164 digits, or masked (e.g. \"*******12345\") when the workspace hides numbers from agents. Never unmasked here.","type":["string","null"]},"phone_masked":{"type":"boolean"},"whatsapp_user_id":{"type":["string","null"]},"dnd":{"type":"boolean","description":"Do-not-disturb: the contact receives no broadcasts/marketing."},"starred":{"description":"null only when it could not be read this time (`unavailable` includes profile_extras).","type":["boolean","null"]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"email":{"type":["string","null"]},"web_visitor_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"attributes":{"description":"Every custom field value this staff member may see (manager-only fields are hidden from agents; deleted fields never appear), at most 100. Text values longer than 2000 characters are clipped.","type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The custom field key (as in `GET /v1/custom-fields`)."},"label":{"description":"The field label shown in the panel.","type":["string","null"]},"type":{"description":"text, textarea, number, int, float, decimal, email, phone, url, select, radio, multiselect, checkbox, boolean, date or datetime.","type":["string","null"]},"value":{"description":"The value as the panel shows it: text; checkbox/boolean \"Yes\"/\"No\"; date \"YYYY-MM-DD\"; datetime \"YYYY-MM-DD HH:MM:SS\" (UTC); multiselect \"a, b\"; int/float numbers; decimal a string with 8 decimals."},"display":{"description":"value as text.","type":["string","null"]},"typed_value":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]},{"type":"null"}],"description":"value typed by the field type: number/int/float/decimal → number; checkbox/boolean → true/false; date → \"YYYY-MM-DD\"; datetime → ISO-8601 UTC; multiselect → array of the chosen values; select/radio/text/… → string. null when empty or unreadable."}},"required":["key","label","type","value","display","typed_value"],"additionalProperties":false}},"conversations":{"description":"Newest first (at most 10), a timeline summary; read messages with the inbox tools.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"channel_id":{"type":["string","null"]},"state":{"type":["string","null"]},"assigned":{"type":"boolean"},"assigned_staff_id":{"type":["string","null"]},"created_at":{"type":["string","null"]},"last_activity_at":{"type":["string","null"]}},"required":["id","channel_id","state","assigned","assigned_staff_id","created_at","last_activity_at"],"additionalProperties":false}},"last_activity_at":{"description":"Latest conversation activity (from the conversation list).","type":["string","null"]},"unavailable":{"description":"Present only when part of the contact could not be read this time (retry later for it): profile_extras = starred, createdAt, updatedAt and webVisitorId are null because they are unknown, not empty; conversations = the timeline (and lastActivityAt) is empty because it could not be read, not because there are none.","type":"array","items":{"type":"string","enum":["profile_extras","conversations"]}}},"required":["id","name","phone","phone_masked","whatsapp_user_id","dnd","starred","created_at","updated_at"]},"examples":{"phone":{"summary":"Look up by phone","value":{"id":"48213","name":"Jane Doe","phone":"+15555550123","phone_masked":false,"email":"jane@example.com","dnd":false,"starred":false,"tags":[{"id":"17","name":"vip"}],"groups":[{"id":"5","name":"Newsletter"}],"created_at":"2026-09-20T08:14:03Z","updated_at":"2026-09-23T16:40:11Z","whatsapp_user_id":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Too many other contacts' numbers contain this one to find it exactly (`reason: lookup_incomplete`): look the contact up by id instead.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Too many other contacts' numbers contain this one to find it exactly (`reason: lookup_incomplete`): look the contact up by id instead.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Too many other contacts' numbers contain this one to find it exactly (`reason: lookup_incomplete`): look the contact up by id instead.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No contact has this number.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No contact has this number.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No contact has this number.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_get_contact","x-platform-ops-path":"/ops/crm_get_contact","x-platform-group":"contacts","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Too many other contacts' numbers contain this one to find it exactly (`reason: lookup_incomplete`): look the contact up by id instead."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No contact has this number."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"phone","summary":"Look up by phone","path":{},"query":{"phone":"+15555550123"},"response":{"status":200,"body":{"id":"48213","name":"Jane Doe","phone":"+15555550123","phone_masked":false,"email":"jane@example.com","dnd":false,"starred":false,"tags":[{"id":"17","name":"vip"}],"groups":[{"id":"5","name":"Newsletter"}],"created_at":"2026-09-20T08:14:03Z","updated_at":"2026-09-23T16:40:11Z","whatsapp_user_id":null}}}]}},"/contacts/count":{"get":{"operationId":"countContacts","summary":"Count contacts","description":"Counts contacts that match the same filters as **List contacts**, without listing them. Handy before a big sync.","tags":["contacts"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"query","in":"query","required":false,"description":"Name or phone contains this text.","schema":{"description":"Name or phone contains this text.","type":"string","minLength":1,"maxLength":100}},{"name":"group_ids","in":"query","required":false,"description":"Contacts in ANY of these groups.","schema":{"description":"Contacts in ANY of these groups.","maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Group id (numeric id)."}},"style":"form","explode":true},{"name":"tag_ids","in":"query","required":false,"description":"Contacts with ANY of these tags (repeat the parameter).","schema":{"description":"Contacts with ANY of these tags (repeat the parameter).","maxItems":50,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Tag id (numeric id)."}},"style":"form","explode":true,"x-platform-picker":"tags"},{"name":"starred","in":"query","required":false,"description":"`true` = starred contacts only.","schema":{"description":"`true` = starred contacts only.","type":"boolean"}},{"name":"dnd","in":"query","required":false,"description":"`true` = do-not-disturb on; `false` = can receive broadcasts.","schema":{"description":"`true` = do-not-disturb on; `false` = can receive broadcasts.","type":"boolean"}},{"name":"not_in_any_group","in":"query","required":false,"description":"`true` = contacts in no group.","schema":{"description":"`true` = contacts in no group.","type":"boolean"}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The count.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"approximate":{"type":"boolean","description":"true when the count is an estimate."},"resolved_dates":{"description":"Relative or local dates in filter and the absolute instants they were run with.","type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"input":{"type":"string"},"value":{"type":"string"}},"required":["path","input","value"],"additionalProperties":false}},"warnings":{"description":"Filter conditions that may not mean what they look like: {path, message}.","type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["count","approximate"]},"examples":{"dnd":{"summary":"How many contacts opted out","value":{"count":312,"approximate":false}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_count_contacts","x-platform-ops-path":"/ops/crm_count_contacts","x-platform-group":"contacts","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"dnd","summary":"How many contacts opted out","path":{},"query":{"dnd":true},"response":{"status":200,"body":{"count":312,"approximate":false}}}]},"post":{"operationId":"countContactsByFilter","summary":"Count contacts by filter","description":"Counts the contacts an advanced filter (the **Search contacts** format) or a saved filter matches, without listing them. `approximate` is `true` when the number is an estimate.","tags":["contacts"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filter":{"description":"The advanced filter (see **Search contacts**).","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"saved_filter_id":{"description":"Count the contacts of a saved contact filter.","anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}]}},"additionalProperties":false},"examples":{"no-reply":{"summary":"Contacts that read broadcast 88 but did not reply","value":{"filter":{"broadcasts":{"some":{"id":{"eq":"88"},"message_status":{"eq":"not_responded"}}}}}}}}}},"responses":{"200":{"description":"The count.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"approximate":{"type":"boolean","description":"true when the count is an estimate."},"resolved_dates":{"description":"Relative or local dates in filter and the absolute instants they were run with.","type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"input":{"type":"string"},"value":{"type":"string"}},"required":["path","input","value"],"additionalProperties":false}},"warnings":{"description":"Filter conditions that may not mean what they look like: {path, message}.","type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["count","approximate"]},"examples":{"no-reply":{"summary":"Contacts that read broadcast 88 but did not reply","value":{"count":412,"approximate":false}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid: each problem names its field and how to fix it. `reason` names the class when there is one: `filter_too_deep`, `filter_too_many_conditions`, `filter_list_too_long`, `filter_string_too_long`, `filter_regex_too_long`, `filter_regex_invalid`, `filter_too_large`, `saved_filter_cycle`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid: each problem names its field and how to fix it. `reason` names the class when there is one: `filter_too_deep`, `filter_too_many_conditions`, `filter_list_too_long`, `filter_string_too_long`, `filter_regex_too_long`, `filter_regex_invalid`, `filter_too_large`, `saved_filter_cycle`.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid: each problem names its field and how to fix it. `reason` names the class when there is one: `filter_too_deep`, `filter_too_many_conditions`, `filter_list_too_long`, `filter_string_too_long`, `filter_regex_too_long`, `filter_regex_invalid`, `filter_too_large`, `saved_filter_cycle`.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The filter or sort compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The filter or sort compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`).","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The filter or sort compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`).","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`).","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`).","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"502":{"description":"`upstream_error`: The contacts service could not run this filter (`reason: filter_failed`), e.g. a regular expression its engine gives up on. Simplify the filter; retrying the same one fails again.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_error":{"summary":"The contacts service could not run this filter (`reason: filter_failed`), e.g. a regular expression its engine gives up on. Simplify the filter; retrying the same one fails again.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_error","title":"A connected service answered unexpectedly","status":502,"detail":"The contacts service could not run this filter (`reason: filter_failed`), e.g. a regular expression its engine gives up on. Simplify the filter; retrying the same one fails again.","code":"upstream_error","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`service_unconfigured`: Advanced filters are switched off on this server (`reason: advanced_filter_disabled`). `upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unconfigured":{"summary":"Advanced filters are switched off on this server (`reason: advanced_filter_disabled`).","value":{"type":"https://dev.wa-api.cloud/errors/service_unconfigured","title":"This feature is not set up here","status":503,"detail":"Advanced filters are switched off on this server (`reason: advanced_filter_disabled`).","code":"service_unconfigured","request_id":"req_01J8ZEXAMPLE0000000000000"}},"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The filter took too long to run (`reason: query_timeout`): narrow it.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The filter took too long to run (`reason: query_timeout`): narrow it.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The filter took too long to run (`reason: query_timeout`): narrow it.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_count_contacts","x-platform-ops-path":"/ops/crm_count_contacts","x-platform-group":"contacts","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid: each problem names its field and how to fix it. `reason` names the class when there is one: `filter_too_deep`, `filter_too_many_conditions`, `filter_list_too_long`, `filter_string_too_long`, `filter_regex_too_long`, `filter_regex_invalid`, `filter_too_large`, `saved_filter_cycle`."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The filter or sort compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`)."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_error","status":502,"when":"The contacts service could not run this filter (`reason: filter_failed`), e.g. a regular expression its engine gives up on. Simplify the filter; retrying the same one fails again."},{"code":"service_unconfigured","status":503,"when":"Advanced filters are switched off on this server (`reason: advanced_filter_disabled`)."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The filter took too long to run (`reason: query_timeout`): narrow it."}],"x-platform-examples":[{"name":"no-reply","summary":"Contacts that read broadcast 88 but did not reply","path":{},"query":{},"body":{"filter":{"broadcasts":{"some":{"id":{"eq":"88"},"message_status":{"eq":"not_responded"}}}}},"response":{"status":200,"body":{"count":412,"approximate":false}}}]}},"/groups":{"get":{"operationId":"listGroups","summary":"List contact groups","description":"Lists the contact groups in your workspace: the audiences you broadcast to and filter by.","tags":["groups"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"search","in":"query","required":false,"description":"Name contains this text.","schema":{"description":"Name contains this text.","type":"string","minLength":1,"maxLength":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of groups.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"emoji":{"type":["string","null"]}},"required":["id","name","emoji"],"additionalProperties":false}},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","next_cursor"]},"examples":{"all":{"summary":"All groups","value":{"data":[{"id":"5","name":"Newsletter","emoji":"📰"},{"id":"6","name":"VIP customers","emoji":null}],"next_cursor":null,"total":2}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_list_groups","x-platform-ops-path":"/ops/crm_list_groups","x-platform-group":"groups","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"all","summary":"All groups","path":{},"query":{},"response":{"status":200,"body":{"data":[{"id":"5","name":"Newsletter","emoji":"📰"},{"id":"6","name":"VIP customers","emoji":null}],"next_cursor":null,"total":2}}}]},"post":{"operationId":"createGroup","summary":"Create a contact group","description":"Creates a contact group. If a group with the same name exists (case does not matter), that one is returned with `created: false`, so calling twice is safe.\n\nAdd contacts to it with **Add contacts to a group**.","tags":["groups"],"security":[{"api_key":["crm:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Group name (any language)."},"emoji":{"description":"One emoji shown next to the name, e.g. `⭐`.","type":"string","minLength":1,"maxLength":10}},"required":["name"],"additionalProperties":false},"examples":{"vip":{"summary":"Create a VIP group","value":{"name":"VIP customers","emoji":"⭐"}}}}}},"responses":{"200":{"description":"The group, and whether it was created.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"group":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"emoji":{"type":["string","null"]}},"required":["id","name","emoji"],"additionalProperties":false},"created":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["group","created"]},"examples":{"vip":{"summary":"Create a VIP group","value":{"group":{"id":"6","name":"VIP customers","emoji":"⭐"},"created":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_create_group","x-platform-ops-path":"/ops/crm_create_group","x-platform-group":"groups","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Delete the group with **Delete a contact group** (its contacts are kept).","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"vip","summary":"Create a VIP group","path":{},"query":{},"body":{"name":"VIP customers","emoji":"⭐"},"response":{"status":200,"body":{"group":{"id":"6","name":"VIP customers","emoji":"⭐"},"created":true}}}]}},"/custom-fields":{"get":{"operationId":"listCustomFields","summary":"List custom fields","description":"Lists the custom fields contacts can carry: the `key` you use in `attributes`, the label your team sees, the type and, for choice fields, the allowed options.","tags":["custom-fields"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"search","in":"query","required":false,"description":"Key or label contains this text.","schema":{"description":"Key or label contains this text.","type":"string","minLength":1,"maxLength":100}},{"name":"type","in":"query","required":false,"description":"Only fields of this type.","schema":{"description":"Only fields of this type.","type":"string","enum":["text","textarea","select","multiselect","checkbox","radio","date","datetime","number","email","url","phone","int","float","boolean","decimal"]}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of custom fields.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","description":"Use this key in attributes: { \"<key>\": value }."},"label":{"type":["string","null"]},"type":{"type":["string","null"]},"options":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},{"type":"null"}],"description":"Allowed values for select / multiselect / radio fields."},"read_only":{"type":"boolean"},"visibility":{"description":"visible_to_all or manager_only.","type":["string","null"]},"in_use":{"type":["boolean","null"]},"created_at":{"type":["string","null"]}},"required":["id","key","label","type","options","read_only","visibility","in_use","created_at"],"additionalProperties":false}},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","next_cursor"]},"examples":{"all":{"summary":"All custom fields","value":{"data":[{"id":"31","key":"order_count","label":"Orders","type":"number","options":null,"read_only":false,"visibility":"visible_to_all","in_use":true,"created_at":"2026-09-01T08:00:00Z"},{"id":"32","key":"loyalty_tier","label":"Loyalty tier","type":"select","options":[{"label":"Gold","value":"gold"},{"label":"Silver","value":"silver"}],"read_only":false,"visibility":"visible_to_all","in_use":false,"created_at":"2026-09-02T08:00:00Z"}],"next_cursor":null,"total":2}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_list_custom_fields","x-platform-ops-path":"/ops/crm_list_custom_fields","x-platform-group":"custom-fields","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"all","summary":"All custom fields","path":{},"query":{},"response":{"status":200,"body":{"data":[{"id":"31","key":"order_count","label":"Orders","type":"number","options":null,"read_only":false,"visibility":"visible_to_all","in_use":true,"created_at":"2026-09-01T08:00:00Z"},{"id":"32","key":"loyalty_tier","label":"Loyalty tier","type":"select","options":[{"label":"Gold","value":"gold"},{"label":"Silver","value":"silver"}],"read_only":false,"visibility":"visible_to_all","in_use":false,"created_at":"2026-09-02T08:00:00Z"}],"next_cursor":null,"total":2}}}]},"post":{"operationId":"createCustomField","summary":"Create a custom field","description":"Creates a custom field for contacts.\n\n- `key`: lower-case snake_case starting with a letter (a–z, 0–9, `_`, up to 64), unique in your workspace. Reserved names such as `name` or `phone_number` are refused.\n- `type`: `select`, `radio` and `multiselect` need `options` (unique values); every other type takes none.\n- A workspace has at most 100 custom fields.\n\nA key that already exists is refused with `409` (`reason: duplicate`), so a retry never makes a twin.","tags":["custom-fields"],"security":[{"api_key":["crm:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":64,"description":"Unique key, e.g. `loyalty_tier`. Used in `attributes` and message variables."},"label":{"type":"string","minLength":1,"maxLength":255,"description":"The label your team sees."},"type":{"type":"string","enum":["text","textarea","select","multiselect","checkbox","radio","date","datetime","number","email","url","phone","int","float","boolean","decimal"],"description":"Field type."},"options":{"description":"Choices for `select`, `radio` and `multiselect`: strings (label = value) or `{label, value}`.","maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":255},"value":{"type":"string","minLength":1,"maxLength":255}},"required":["label","value"]}]}},"placeholder":{"description":"Hint shown in the empty input.","type":"string","maxLength":255},"read_only":{"default":false,"description":"`true` = your team cannot edit the value in the app; the API still can.","type":"boolean"},"visibility":{"default":"visible_to_all","description":"`manager_only` hides the field from agents.","type":"string","enum":["visible_to_all","manager_only"]}},"required":["key","label","type"],"additionalProperties":false},"examples":{"tier":{"summary":"A loyalty tier with three choices","value":{"key":"loyalty_tier","label":"Loyalty tier","type":"select","options":["gold","silver","bronze"]}}}}}},"responses":{"201":{"description":"The new custom field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"field":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","description":"Use this key in attributes: { \"<key>\": value }."},"label":{"type":["string","null"]},"type":{"type":["string","null"]},"options":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},{"type":"null"}],"description":"Allowed values for select / multiselect / radio fields."},"read_only":{"type":"boolean"},"visibility":{"description":"visible_to_all or manager_only.","type":["string","null"]},"in_use":{"type":["boolean","null"]},"created_at":{"type":["string","null"]}},"required":["id","key","label","type","options","read_only","visibility","in_use","created_at"],"additionalProperties":false},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["field"]},"examples":{"tier":{"summary":"A loyalty tier with three choices","value":{"field":{"id":"32","key":"loyalty_tier","label":"Loyalty tier","type":"select","options":[{"label":"gold","value":"gold"},{"label":"silver","value":"silver"},{"label":"bronze","value":"bronze"}],"read_only":false,"visibility":"visible_to_all","in_use":false,"created_at":"2026-09-02T08:00:00Z"}}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The workspace already has 100 custom fields (`reason: custom_field_limit`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The workspace already has 100 custom fields (`reason: custom_field_limit`).","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The workspace already has 100 custom fields (`reason: custom_field_limit`).","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: A custom field with this key already exists (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"A custom field with this key already exists (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"A custom field with this key already exists (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_create_custom_field","x-platform-ops-path":"/ops/crm_create_custom_field","x-platform-group":"custom-fields","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Delete it with **Delete a custom field**.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The workspace already has 100 custom fields (`reason: custom_field_limit`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"A custom field with this key already exists (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"tier","summary":"A loyalty tier with three choices","path":{},"query":{},"body":{"key":"loyalty_tier","label":"Loyalty tier","type":"select","options":["gold","silver","bronze"]},"response":{"status":201,"body":{"field":{"id":"32","key":"loyalty_tier","label":"Loyalty tier","type":"select","options":[{"label":"gold","value":"gold"},{"label":"silver","value":"silver"},{"label":"bronze","value":"bronze"}],"read_only":false,"visibility":"visible_to_all","in_use":false,"created_at":"2026-09-02T08:00:00Z"}}}}]}},"/custom-fields/{custom_field_id}":{"get":{"operationId":"getCustomField","summary":"Get a custom field","description":"Returns one custom field: its `key`, label, type, the options of a choice field, placeholder, `read_only`, `visibility`, whether contacts hold values in it (`in_use`) and when it was created and last changed.\n\nA field that is visible to managers only (`visibility: manager_only`) is `404` for a key whose staff member is not a manager, exactly as if it did not exist, and it is not in **List custom fields** for them either.","tags":["custom-fields"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"custom_field_id","in":"path","required":true,"description":"The custom field id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Custom field id (`GET /v1/custom-fields`) (numeric id)."}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The custom field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"key":{"type":"string","description":"Use this key in attributes: { \"<key>\": value }."},"label":{"type":["string","null"]},"type":{"type":["string","null"]},"options":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},{"type":"null"}],"description":"Allowed values for select / multiselect / radio fields."},"read_only":{"type":"boolean"},"visibility":{"description":"visible_to_all or manager_only.","type":["string","null"]},"in_use":{"type":["boolean","null"]},"created_at":{"type":["string","null"]},"placeholder":{"description":"Hint shown in the empty input (none for checkbox, boolean and choice fields).","type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","key","label","type","options","read_only","visibility","in_use","created_at","placeholder","updated_at"]},"examples":{"one":{"summary":"Read a choice field","value":{"id":"32","key":"loyalty_tier","label":"Loyalty tier","type":"select","options":[{"label":"Gold","value":"gold"},{"label":"Silver","value":"silver"}],"read_only":false,"visibility":"visible_to_all","in_use":true,"created_at":"2026-09-02T08:00:00Z","placeholder":null,"updated_at":"2026-09-20T10:30:00Z"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No custom field with this id in your workspace, or it is visible to managers only and your key's staff member is not one.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No custom field with this id in your workspace, or it is visible to managers only and your key's staff member is not one.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No custom field with this id in your workspace, or it is visible to managers only and your key's staff member is not one.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_get_custom_field","x-platform-ops-path":"/ops/crm_get_custom_field","x-platform-group":"custom-fields","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No custom field with this id in your workspace, or it is visible to managers only and your key's staff member is not one."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"one","summary":"Read a choice field","path":{"custom_field_id":"32"},"query":{},"response":{"status":200,"body":{"id":"32","key":"loyalty_tier","label":"Loyalty tier","type":"select","options":[{"label":"Gold","value":"gold"},{"label":"Silver","value":"silver"}],"read_only":false,"visibility":"visible_to_all","in_use":true,"created_at":"2026-09-02T08:00:00Z","placeholder":null,"updated_at":"2026-09-20T10:30:00Z"}}}]},"patch":{"operationId":"updateCustomField","summary":"Update a custom field","description":"Changes only what you pass: `label`, `type`, the options of a choice field, `placeholder`, `read_only` and `visibility`. Everything else stays as it is.\n\n- **The `key` never changes**: contacts' values, chatbots and messages use it. Sending a different `key` is `400` (`reason: key_immutable`); create a new field instead.\n- **Options**: `add_options` appends choices (strings, or `{label, value}`; values unique), `rename_options` gives existing options a new label by `value` (the value, and every stored answer, stays), `remove_options` takes options out. A choice field keeps at least one option, and at most 500.\n- **While contacts hold values** (`in_use: true`) the `type` cannot change (`409`, `reason: type_change_in_use`: the values would be hidden) and options cannot be removed (`409`, `reason: option_in_use`): relabel them instead. On an unused field a new choice type needs `add_options`, and a non-choice type drops the options.\n- Checkbox, boolean and choice fields have no placeholder.\n- Labels are unique: a label another field has is `409` (`reason: duplicate_label`).\n\nOnly managers can change custom fields. A request that changes nothing writes nothing and answers `changed: []`: adding an option exactly as it already is and removing a value that is not there change nothing, so sending the same PATCH again is safe. If the field is changed elsewhere (in the panel, say) while your request runs, nothing is written and the answer is `409` (`reason: changed_concurrently`): read the field again and send your change against what it is now. Contacts show the new label on their next read. Try it with `?dry_run=true`: every check runs and nothing changes.","tags":["custom-fields"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"custom_field_id","in":"path","required":true,"description":"The custom field id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Custom field id (`GET /v1/custom-fields`) (numeric id)."}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"Optional: the field's current key, to make sure you change the right field. It cannot change.","type":"string","minLength":1,"maxLength":64},"label":{"description":"New label (any language).","type":"string","minLength":1,"maxLength":255},"type":{"description":"New type. Only while no contact holds a value.","type":"string","enum":["text","textarea","select","multiselect","checkbox","radio","date","datetime","number","email","url","phone","int","float","boolean","decimal"]},"add_options":{"description":"Choices to add: strings (label = value) or `{label, value}`.","maxItems":100,"type":"array","items":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":255},"value":{"type":"string","minLength":1,"maxLength":255}},"required":["label","value"]}]}},"rename_options":{"description":"`{value, label}`: a new label for the option with this value.","maxItems":100,"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":255},"label":{"type":"string","minLength":1,"maxLength":255}},"required":["value","label"]}},"remove_options":{"description":"Option values to remove. Only while no contact holds a value.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":255}},"placeholder":{"description":"New hint shown in the empty input; `null` clears it.","anyOf":[{"type":"string","maxLength":255},{"type":"null"}]},"read_only":{"description":"`true` = your team cannot edit the value in the app; the API still can.","type":"boolean"},"visibility":{"description":"`manager_only` hides the field from agents.","type":"string","enum":["visible_to_all","manager_only"]}},"additionalProperties":false},"examples":{"relabel":{"summary":"Rename a field and add a choice","value":{"label":"Loyalty level","add_options":["platinum"],"rename_options":[{"value":"gold","label":"Gold ✨"}]}}}}}},"responses":{"200":{"description":"The field after the change, and which properties changed (`[]` = nothing to do).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"field":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","description":"Use this key in attributes: { \"<key>\": value }."},"label":{"type":["string","null"]},"type":{"type":["string","null"]},"options":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"],"additionalProperties":false}},{"type":"null"}],"description":"Allowed values for select / multiselect / radio fields."},"read_only":{"type":"boolean"},"visibility":{"description":"visible_to_all or manager_only.","type":["string","null"]},"in_use":{"type":["boolean","null"]},"created_at":{"type":["string","null"]},"placeholder":{"description":"Hint shown in the empty input (none for checkbox, boolean and choice fields).","type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","key","label","type","options","read_only","visibility","in_use","created_at","placeholder","updated_at"],"additionalProperties":false},"changed":{"type":"array","items":{"type":"string"},"description":"The properties this call changed; [] = it already was like this (nothing written)."},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["field","changed"]},"examples":{"relabel":{"summary":"Rename a field and add a choice","value":{"field":{"id":"32","key":"loyalty_tier","label":"Loyalty level","type":"select","options":[{"label":"Gold ✨","value":"gold"},{"label":"Silver","value":"silver"},{"label":"platinum","value":"platinum"}],"read_only":false,"visibility":"visible_to_all","in_use":true,"created_at":"2026-09-02T08:00:00Z","placeholder":null,"updated_at":"2026-09-29T09:00:00Z"},"changed":["label","options"]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Nothing to change; a different `key` (`reason: key_immutable`); options on a field that is not a choice field; an unknown or repeated option value; a placeholder on a type that has none.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Nothing to change; a different `key` (`reason: key_immutable`); options on a field that is not a choice field; an unknown or repeated option value; a placeholder on a type that has none.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Nothing to change; a different `key` (`reason: key_immutable`); options on a field that is not a choice field; an unknown or repeated option value; a placeholder on a type that has none.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: Your key's staff member is not a manager. `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"Your key's staff member is not a manager.","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"Your key's staff member is not a manager.","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No custom field with this id in your workspace (or it is visible to managers only and your key's staff member is not one).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No custom field with this id in your workspace (or it is visible to managers only and your key's staff member is not one).","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No custom field with this id in your workspace (or it is visible to managers only and your key's staff member is not one).","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Contacts hold values: the type cannot change (`reason: type_change_in_use`) and options cannot be removed (`reason: option_in_use`); or another field has this label (`reason: duplicate_label`); or the field changed elsewhere while the request ran (`reason: changed_concurrently`: read it again, then retry). Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Contacts hold values: the type cannot change (`reason: type_change_in_use`) and options cannot be removed (`reason: option_in_use`); or another field has this label (`reason: duplicate_label`); or the field changed elsewhere while the request ran (`reason: changed_concurrently`: read it again, then retry). Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Contacts hold values: the type cannot change (`reason: type_change_in_use`) and options cannot be removed (`reason: option_in_use`); or another field has this label (`reason: duplicate_label`); or the field changed elsewhere while the request ran (`reason: changed_concurrently`: read it again, then retry). Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_update_custom_field","x-platform-ops-path":"/ops/crm_update_custom_field","x-platform-group":"custom-fields","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Send the old values back (`rename_options` with the old labels). Removed options can be added again with the same values.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Nothing to change; a different `key` (`reason: key_immutable`); options on a field that is not a choice field; an unknown or repeated option value; a placeholder on a type that has none."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"Your key's staff member is not a manager."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No custom field with this id in your workspace (or it is visible to managers only and your key's staff member is not one)."},{"code":"conflict","status":409,"when":"Contacts hold values: the type cannot change (`reason: type_change_in_use`) and options cannot be removed (`reason: option_in_use`); or another field has this label (`reason: duplicate_label`); or the field changed elsewhere while the request ran (`reason: changed_concurrently`: read it again, then retry). Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"relabel","summary":"Rename a field and add a choice","path":{"custom_field_id":"32"},"query":{},"body":{"label":"Loyalty level","add_options":["platinum"],"rename_options":[{"value":"gold","label":"Gold ✨"}]},"response":{"status":200,"body":{"field":{"id":"32","key":"loyalty_tier","label":"Loyalty level","type":"select","options":[{"label":"Gold ✨","value":"gold"},{"label":"Silver","value":"silver"},{"label":"platinum","value":"platinum"}],"read_only":false,"visibility":"visible_to_all","in_use":true,"created_at":"2026-09-02T08:00:00Z","placeholder":null,"updated_at":"2026-09-29T09:00:00Z"},"changed":["label","options"]}}}]},"delete":{"operationId":"deleteCustomField","summary":"Delete a custom field","description":"Deletes one custom field. **Every contact loses its value for this field**: it disappears from contacts, filters and imports, and chatbots or messages that use the field as a variable get an empty value.\n\nTry it with `?dry_run=true` first: the field is looked up, nothing is deleted. `in_use: true` in the answer means something still used it.","tags":["custom-fields"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"custom_field_id","in":"path","required":true,"description":"The custom field id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Custom field id (`GET /v1/custom-fields`) (numeric id)."}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"Deleted.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"key":{"type":"string"},"label":{"type":["string","null"]},"in_use":{"type":["boolean","null"]},"deleted":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","key","label","in_use","deleted"]},"examples":{"delete":{"summary":"Delete a field you no longer use","value":{"id":"32","key":"loyalty_tier","label":"Loyalty tier","in_use":false,"deleted":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No custom field with this id in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No custom field with this id in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No custom field with this id in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_delete_custom_field","x-platform-ops-path":"/ops/crm_delete_custom_field","x-platform-group":"custom-fields","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":"delete","x-platform-undo":"Cannot be undone. The stored values are not given back if you create the field again.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No custom field with this id in your workspace."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"delete","summary":"Delete a field you no longer use","path":{"custom_field_id":"32"},"query":{},"response":{"status":200,"body":{"id":"32","key":"loyalty_tier","label":"Loyalty tier","in_use":false,"deleted":true}}}]}},"/tags":{"get":{"operationId":"listTags","summary":"List contact tags","description":"Lists the contact tags in your workspace. Conversation tags are separate.","tags":["tags"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"search","in":"query","required":false,"description":"Name contains this text.","schema":{"description":"Name contains this text.","type":"string","minLength":1,"maxLength":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of tags.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"color":{"type":["string","null"]}},"required":["id","name","color"],"additionalProperties":false}},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","next_cursor"]},"examples":{"all":{"summary":"All tags","value":{"data":[{"id":"17","name":"vip","color":"#22c55e"},{"id":"18","name":"shopify","color":null}],"next_cursor":null,"total":2}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_list_tags","x-platform-ops-path":"/ops/crm_list_tags","x-platform-group":"tags","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"all","summary":"All tags","path":{},"query":{},"response":{"status":200,"body":{"data":[{"id":"17","name":"vip","color":"#22c55e"},{"id":"18","name":"shopify","color":null}],"next_cursor":null,"total":2}}}]},"post":{"operationId":"createTag","summary":"Create a tag","description":"Creates a contact tag. If one with the same name exists, that one is returned with `created: false`, so calling twice is safe.","tags":["tags"],"security":[{"api_key":["crm:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Tag name."},"color":{"description":"Hex colour.","type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"required":["name"],"additionalProperties":false},"examples":{"vip":{"summary":"Create a green VIP tag","value":{"name":"vip","color":"#22c55e"}}}}}},"responses":{"200":{"description":"The tag.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"tag":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"color":{"type":["string","null"]}},"required":["id","name","color"],"additionalProperties":false},"created":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["tag","created"]},"examples":{"vip":{"summary":"Create a green VIP tag","value":{"tag":{"id":"17","name":"vip","color":"#22c55e"},"created":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_create_tag","x-platform-ops-path":"/ops/crm_create_tag","x-platform-group":"tags","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Tags can be deleted in the app.","x-platform-events":["tag.created/1"],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"vip","summary":"Create a green VIP tag","path":{},"query":{},"body":{"name":"vip","color":"#22c55e"},"response":{"status":200,"body":{"tag":{"id":"17","name":"vip","color":"#22c55e"},"created":true}}}]}},"/saved-filters":{"get":{"operationId":"listSavedFilters","summary":"List saved filters","description":"Lists the contact (or conversation) filters your team saved in the app. Use `detail=full` to include each stored filter definition.","tags":["contacts"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"type","in":"query","required":false,"description":"`contact` (default) or `conversation` filters.","schema":{"default":"contact","description":"`contact` (default) or `conversation` filters.","type":"string","enum":["contact","conversation"]}},{"name":"search","in":"query","required":false,"description":"Name contains this text.","schema":{"description":"Name contains this text.","type":"string","minLength":1,"maxLength":100}},{"name":"detail","in":"query","required":false,"description":"`summary` (default) or `full` (adds the stored filter definition).","schema":{"default":"summary","description":"`summary` (default) or `full` (adds the stored filter definition).","type":"string","enum":["summary","full"]}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of saved filters.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"type":{"description":"contact or conversation.","type":["string","null"]},"owner_staff_id":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"filter":{"description":"The stored filter definition (detail \"full\" only), as the panel saved it."}},"required":["id","name","description","type","owner_staff_id","updated_at"],"additionalProperties":false}},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","next_cursor"]},"examples":{"contacts":{"summary":"Saved contact filters","value":{"data":[{"id":"7","name":"Dubai VIPs","description":"VIP tag, city Dubai","type":"contact","owner_staff_id":"501","updated_at":"2026-09-02T08:00:00Z"}],"next_cursor":null,"total":1}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_list_saved_filters","x-platform-ops-path":"/ops/crm_list_saved_filters","x-platform-group":"contacts","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"contacts","summary":"Saved contact filters","path":{},"query":{"type":"contact"},"response":{"status":200,"body":{"data":[{"id":"7","name":"Dubai VIPs","description":"VIP tag, city Dubai","type":"contact","owner_staff_id":"501","updated_at":"2026-09-02T08:00:00Z"}],"next_cursor":null,"total":1}}}]},"post":{"operationId":"createSavedFilter","summary":"Save a contact filter","description":"Saves an advanced contact filter under a name. Your whole team sees it, it opens in the app's contacts page, and **Search contacts** can apply it by id.\n\nIt is checked first, like **Check a contact filter**. Relative dates are saved as the absolute dates they mean now.\n\nTry it with `?dry_run=true` first: every check the save runs, and the answer is the saved filter exactly as it would be stored (your name, your filter with its dates made absolute, `id: null`); nothing is saved and no `Idempotency-Key` is needed. Add `count=true` to also count the contacts it would match; if counting fails, the preview still answers (`count: null` and `count_error`).","tags":["contacts"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"count","in":"query","required":false,"description":"With `dry_run=true`: also count the contacts it would match.","schema":{"description":"With `dry_run=true`: also count the contacts it would match.","type":"boolean"}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Name shown in the app (1–255 characters)."},"description":{"description":"Optional description (up to 1000 characters).","type":"string","maxLength":1000},"filter":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The filter to save (the **Search contacts** format)."}},"required":["name","filter"],"additionalProperties":false},"examples":{"vip-dubai":{"summary":"Save \"Dubai VIPs\"","value":{"name":"Dubai VIPs","filter":{"attributes":{"some":{"attributeName":{"eq":"city"},"stringValue":{"eq":"Dubai"}}}}}},"preview":{"summary":"Preview a save and count its matches (dry run)","value":{"name":"New this month","filter":{"createdAt":{"gte":"start_of_month"}}}}}}}},"responses":{"201":{"description":"The saved filter (with `dry_run=true`: as it would be saved, `id: null`).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"saved_filter":{"type":"object","properties":{"id":{"description":"null in a dry run: known only when it is saved.","type":["string","null"]},"name":{"type":"string"},"description":{"type":["string","null"]},"owner_staff_id":{"type":["string","null"]},"filter":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The definition as stored: the panel format, dates absolute."},"updated_at":{"description":"null in a dry run.","type":["string","null"]}},"required":["id","name","description","owner_staff_id","filter","updated_at"],"additionalProperties":false},"resolved_dates":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"input":{"type":"string"},"value":{"type":"string"}},"required":["path","input","value"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false},"description":"Filter conditions that may not mean what they look like: {path, message}."},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."},"count":{"description":"With dryRun + count: contacts it would match now (null when the count failed: see countError).","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"approximate":{"description":"With count: the service counted approximately.","type":["boolean","null"]},"count_error":{"description":"Why the count is missing. The preview itself is still valid.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["saved_filter","resolved_dates","warnings"]},"examples":{"vip-dubai":{"summary":"Save \"Dubai VIPs\"","value":{"saved_filter":{"id":"7","name":"Dubai VIPs","description":null,"owner_staff_id":"501","filter":{"attributes":{"some":{"attributeName":{"eq":"city"},"stringValue":{"eq":"Dubai"}}}},"updated_at":"2026-09-30T08:00:00.000Z"},"resolved_dates":[],"warnings":[]}},"preview":{"summary":"Preview a save and count its matches (dry run)","value":{"saved_filter":{"id":null,"name":"New this month","description":null,"owner_staff_id":"501","filter":{"createdAt":{"gte":"2026-08-31T20:00:00.000Z"}},"updated_at":null},"resolved_dates":[{"path":"filter.createdAt.gte","input":"start_of_month","value":"2026-08-31T20:00:00.000Z"}],"warnings":[],"dry_run":true,"count":120,"approximate":false}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid (each problem has its field, and `reason` names the class when there is one, as for **Search contacts**), it is larger than 32 KB, or `count=true` without `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid (each problem has its field, and `reason` names the class when there is one, as for **Search contacts**), it is larger than 32 KB, or `count=true` without `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid (each problem has its field, and `reason` names the class when there is one, as for **Search contacts**), it is larger than 32 KB, or `count=true` without `dry_run=true`.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The filter compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The filter compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`).","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The filter compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`).","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`).","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`).","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_create_saved_filter","x-platform-ops-path":"/ops/crm_create_saved_filter","x-platform-group":"contacts","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"native","x-platform-destructive-verb":null,"x-platform-undo":"Delete it with **Delete a saved filter**.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The filter is not valid (each problem has its field, and `reason` names the class when there is one, as for **Search contacts**), it is larger than 32 KB, or `count=true` without `dry_run=true`."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The filter compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"A saved filter it names does not exist in your workspace (`reason: saved_filter_not_found`)."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"vip-dubai","summary":"Save \"Dubai VIPs\"","path":{},"query":{},"body":{"name":"Dubai VIPs","filter":{"attributes":{"some":{"attributeName":{"eq":"city"},"stringValue":{"eq":"Dubai"}}}}},"response":{"status":201,"body":{"saved_filter":{"id":"7","name":"Dubai VIPs","description":null,"owner_staff_id":"501","filter":{"attributes":{"some":{"attributeName":{"eq":"city"},"stringValue":{"eq":"Dubai"}}}},"updated_at":"2026-09-30T08:00:00.000Z"},"resolved_dates":[],"warnings":[]}}},{"name":"preview","summary":"Preview a save and count its matches (dry run)","path":{},"query":{"dry_run":true,"count":true},"body":{"name":"New this month","filter":{"createdAt":{"gte":"start_of_month"}}},"response":{"status":201,"body":{"saved_filter":{"id":null,"name":"New this month","description":null,"owner_staff_id":"501","filter":{"createdAt":{"gte":"2026-08-31T20:00:00.000Z"}},"updated_at":null},"resolved_dates":[{"path":"filter.createdAt.gte","input":"start_of_month","value":"2026-08-31T20:00:00.000Z"}],"warnings":[],"dry_run":true,"count":120,"approximate":false}}}]}},"/saved-filters/{saved_filter_id}":{"get":{"operationId":"getSavedFilter","summary":"Get a saved filter","description":"Returns one saved filter: its name, description, type (`contact` or `conversation`), who saved it and its stored definition.\n\nEvery saved filter is visible to your whole team (`visible_to: workspace`); only the staff member who saved it (`owner_staff_id`, `owned_by_you`) can change it.\n\n`filter` is the definition exactly as it was saved; for a contact filter that is the format of **Search contacts**, which applies it by id (`saved_filter_id`). A definition over 32 KB is left out (`filter: null`, `filter_too_large: true`).","tags":["contacts"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"saved_filter_id","in":"path","required":true,"description":"The saved filter id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Saved filter id (`GET /v1/saved-filters`) (numeric id)."}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The saved filter.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"type":{"description":"contact or conversation.","type":["string","null"]},"owner_staff_id":{"description":"The staff member who saved it; only they can change or delete it.","type":["string","null"]},"owned_by_you":{"description":"true = you saved it (you may change it in the panel).","type":["boolean","null"]},"visible_to":{"type":"string","const":"workspace","description":"Every saved filter is visible to all staff of the workspace."},"filter":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"The stored definition exactly as the panel saved it (for a contact filter: the `GET /v1/contacts` `filter` format). null when larger than 32000 bytes (filterTooLarge)."},"filter_too_large":{"type":"boolean"},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","name","description","type","owner_staff_id","owned_by_you","visible_to","filter","filter_too_large","created_at","updated_at"]},"examples":{"one":{"summary":"Read a saved contact filter","value":{"id":"7","name":"Dubai VIPs","description":"VIP tag, city Dubai","type":"contact","owner_staff_id":"501","owned_by_you":true,"visible_to":"workspace","filter":{"attributes":{"some":{"attributeName":{"eq":"city"},"stringValue":{"eq":"Dubai"}}}},"filter_too_large":false,"created_at":"2026-09-01T08:00:00Z","updated_at":"2026-09-02T08:00:00Z"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No saved filter with this id in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No saved filter with this id in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No saved filter with this id in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_get_saved_filter","x-platform-ops-path":"/ops/crm_get_saved_filter","x-platform-group":"contacts","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No saved filter with this id in your workspace."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"one","summary":"Read a saved contact filter","path":{"saved_filter_id":"7"},"query":{},"response":{"status":200,"body":{"id":"7","name":"Dubai VIPs","description":"VIP tag, city Dubai","type":"contact","owner_staff_id":"501","owned_by_you":true,"visible_to":"workspace","filter":{"attributes":{"some":{"attributeName":{"eq":"city"},"stringValue":{"eq":"Dubai"}}}},"filter_too_large":false,"created_at":"2026-09-01T08:00:00Z","updated_at":"2026-09-02T08:00:00Z"}}}]},"patch":{"operationId":"updateSavedFilter","summary":"Change a saved filter","description":"Renames a saved contact filter, changes its description, or replaces its filter. Only the staff member who saved it can change it. Fields you leave out stay as they are. `changes` lists the fields whose saved value differs.\n\nTry it with `?dry_run=true` first: every check the change runs (ownership included), and the answer is the saved filter as it would be after it, with `changes`; nothing is saved. Add `count=true` to also count the contacts it would match; if counting fails, the preview still answers (`count: null` and `count_error`).","tags":["contacts"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"saved_filter_id","in":"path","required":true,"description":"The saved filter id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Saved filter id (`GET /v1/saved-filters`) (numeric id)."}},{"name":"count","in":"query","required":false,"description":"With `dry_run=true`: also count the contacts it would match.","schema":{"description":"With `dry_run=true`: also count the contacts it would match.","type":"boolean"}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New name.","type":"string","minLength":1,"maxLength":255},"description":{"description":"New description; `null` clears it.","anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"filter":{"description":"New filter (replaces the old one).","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"additionalProperties":false},"examples":{"rename":{"summary":"Rename a saved filter","value":{"name":"Dubai VIPs (2026)"}},"preview":{"summary":"Preview a new filter (dry run)","value":{"filter":{"createdAt":{"gte":"-30d"}}}}}}}},"responses":{"200":{"description":"The saved filter as it is now (with `dry_run=true`: as it would be).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"saved_filter":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"owner_staff_id":{"type":["string","null"]},"filter":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The definition as stored: the panel format, dates absolute."},"updated_at":{"description":"null in a dry run.","type":["string","null"]}},"required":["id","name","description","owner_staff_id","filter","updated_at"],"additionalProperties":false},"changes":{"type":"array","items":{"type":"string","enum":["name","description","filter"]},"description":"Fields whose saved value differs after this change (empty: it changes nothing)."},"resolved_dates":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"input":{"type":"string"},"value":{"type":"string"}},"required":["path","input","value"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false},"description":"Filter conditions that may not mean what they look like: {path, message}."},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."},"count":{"description":"With dryRun + count: contacts it would match now (null when the count failed: see countError).","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"approximate":{"description":"With count: the service counted approximately.","type":["boolean","null"]},"count_error":{"description":"Why the count is missing. The preview itself is still valid.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["saved_filter","changes","resolved_dates","warnings"]},"examples":{"rename":{"summary":"Rename a saved filter","value":{"saved_filter":{"id":"7","name":"Dubai VIPs (2026)","description":null,"owner_staff_id":"501","filter":{"attributes":{"some":{"attributeName":{"eq":"city"},"stringValue":{"eq":"Dubai"}}}},"updated_at":"2026-09-30T08:05:00.000Z"},"changes":["name"],"resolved_dates":[],"warnings":[]}},"preview":{"summary":"Preview a new filter (dry run)","value":{"saved_filter":{"id":"7","name":"Dubai VIPs","description":null,"owner_staff_id":"501","filter":{"createdAt":{"gte":"2026-08-31T08:00:00.000Z"}},"updated_at":null},"changes":["filter"],"resolved_dates":[{"path":"filter.createdAt.gte","input":"-30d","value":"2026-08-31T08:00:00.000Z"}],"warnings":[],"dry_run":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The new filter is not valid (as for **Save a contact filter**; a filter may not contain itself: `reason: saved_filter_cycle`), it is larger than 32 KB, what the change keeps from the stored filter breaks the platform's limits (a filter or panel settings over 32 KB saved before the limit existed), the saved filter is a conversation filter, or `count=true` without `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The new filter is not valid (as for **Save a contact filter**; a filter may not contain itself: `reason: saved_filter_cycle`), it is larger than 32 KB, what the change keeps from the stored filter breaks the platform's limits (a filter or panel settings over 32 KB saved before the limit existed), the saved filter is a conversation filter, or `count=true` without `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The new filter is not valid (as for **Save a contact filter**; a filter may not contain itself: `reason: saved_filter_cycle`), it is larger than 32 KB, what the change keeps from the stored filter breaks the platform's limits (a filter or panel settings over 32 KB saved before the limit existed), the saved filter is a conversation filter, or `count=true` without `dry_run=true`.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: Someone else saved it (`reason: not_owner`, with `owner_staff_id`), or the new filter compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"Someone else saved it (`reason: not_owner`, with `owner_staff_id`), or the new filter compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`).","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"Someone else saved it (`reason: not_owner`, with `owner_staff_id`), or the new filter compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`).","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No saved filter with this id in your workspace, or the new filter names one that does not exist (`reason: saved_filter_not_found`).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No saved filter with this id in your workspace, or the new filter names one that does not exist (`reason: saved_filter_not_found`).","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No saved filter with this id in your workspace, or the new filter names one that does not exist (`reason: saved_filter_not_found`).","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_update_saved_filter","x-platform-ops-path":"/ops/crm_update_saved_filter","x-platform-group":"contacts","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"none","x-platform-dry-run":"native","x-platform-destructive-verb":null,"x-platform-undo":"Change it back with the old values (read them first with **Get a saved filter**).","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The new filter is not valid (as for **Save a contact filter**; a filter may not contain itself: `reason: saved_filter_cycle`), it is larger than 32 KB, what the change keeps from the stored filter breaks the platform's limits (a filter or panel settings over 32 KB saved before the limit existed), the saved filter is a conversation filter, or `count=true` without `dry_run=true`."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"Someone else saved it (`reason: not_owner`, with `owner_staff_id`), or the new filter compares phone numbers, which are hidden from this staff member (`reason: phone_hidden`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No saved filter with this id in your workspace, or the new filter names one that does not exist (`reason: saved_filter_not_found`)."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"rename","summary":"Rename a saved filter","path":{"saved_filter_id":"7"},"query":{},"body":{"name":"Dubai VIPs (2026)"},"response":{"status":200,"body":{"saved_filter":{"id":"7","name":"Dubai VIPs (2026)","description":null,"owner_staff_id":"501","filter":{"attributes":{"some":{"attributeName":{"eq":"city"},"stringValue":{"eq":"Dubai"}}}},"updated_at":"2026-09-30T08:05:00.000Z"},"changes":["name"],"resolved_dates":[],"warnings":[]}}},{"name":"preview","summary":"Preview a new filter (dry run)","path":{"saved_filter_id":"7"},"query":{"dry_run":true},"body":{"filter":{"createdAt":{"gte":"-30d"}}},"response":{"status":200,"body":{"saved_filter":{"id":"7","name":"Dubai VIPs","description":null,"owner_staff_id":"501","filter":{"createdAt":{"gte":"2026-08-31T08:00:00.000Z"}},"updated_at":null},"changes":["filter"],"resolved_dates":[{"path":"filter.createdAt.gte","input":"-30d","value":"2026-08-31T08:00:00.000Z"}],"warnings":[],"dry_run":true}}}]},"delete":{"operationId":"deleteSavedFilter","summary":"Delete a saved filter","description":"Deletes a saved contact filter. Only the staff member who saved it can delete it. Contacts are not touched.","tags":["contacts"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"saved_filter_id","in":"path","required":true,"description":"The saved filter id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Saved filter id (`GET /v1/saved-filters`) (numeric id)."}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"Deleted.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"deleted":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","name","deleted"]},"examples":{"delete":{"summary":"Delete a saved filter","value":{"id":"7","name":"Dubai VIPs","deleted":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The saved filter is a conversation filter: these operations change contact filters only.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The saved filter is a conversation filter: these operations change contact filters only.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The saved filter is a conversation filter: these operations change contact filters only.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: Someone else saved it (`reason: not_owner`, with `owner_staff_id`). Checked before anything is asked or deleted. `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"Someone else saved it (`reason: not_owner`, with `owner_staff_id`). Checked before anything is asked or deleted.","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"Someone else saved it (`reason: not_owner`, with `owner_staff_id`). Checked before anything is asked or deleted.","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No saved filter with this id in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No saved filter with this id in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No saved filter with this id in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_delete_saved_filter","x-platform-ops-path":"/ops/crm_delete_saved_filter","x-platform-group":"contacts","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":"delete","x-platform-undo":"Cannot be undone. Save the filter again with **Save a contact filter**.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The saved filter is a conversation filter: these operations change contact filters only."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"Someone else saved it (`reason: not_owner`, with `owner_staff_id`). Checked before anything is asked or deleted."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No saved filter with this id in your workspace."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"delete","summary":"Delete a saved filter","path":{"saved_filter_id":"7"},"query":{},"response":{"status":200,"body":{"id":"7","name":"Dubai VIPs","deleted":true}}}]}},"/contacts/filters/validate":{"post":{"operationId":"validateContactFilter","summary":"Check a contact filter","description":"Checks an advanced contact filter without running a search. Answers `valid` with every problem (`issues`, each with its path), the filter as it would run (relative dates turned into absolute ones in your workspace's timezone), warnings, and with `count: true` how many contacts match.\n\nUse it before saving a filter.","tags":["contacts"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filter":{"description":"The advanced filter to check (see **Search contacts**).","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"saved_filter_id":{"description":"A saved contact filter to include.","anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}]},"count":{"default":false,"description":"`true` = also count the matching contacts.","type":"boolean"}},"additionalProperties":false},"examples":{"relative":{"summary":"Check a filter with a relative date","value":{"filter":{"createdAt":{"gte":"start_of_month"}},"count":true}}}}}},"responses":{"200":{"description":"Whether the filter is valid, and how it would run.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"valid":{"type":"boolean"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"},"reason":{"description":"The refusal class when it has one (filter_too_deep, filter_regex_invalid, saved_filter_not_found, …).","type":"string"}},"required":["path","message"],"additionalProperties":false},"description":"Why it is not valid (empty when valid)."},"filter":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Your filter, normalised: what `POST /v1/saved-filters` would store."},"resolved_dates":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"input":{"type":"string"},"value":{"type":"string"}},"required":["path","input","value"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false},"description":"Filter conditions that may not mean what they look like: {path, message}."},"notes":{"type":"array","items":{"type":"string"},"description":"Normalisations applied."},"conditions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"saved_filters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"description":"Saved filters it uses (applied as part of it)."},"timezone":{"description":"Timezone relative dates were resolved in (null when not valid).","type":["string","null"]},"count":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"approximate":{"type":["boolean","null"]}},"required":["valid","issues","filter","resolved_dates","warnings","notes","conditions","depth","saved_filters","timezone","count","approximate"]},"examples":{"relative":{"summary":"Check a filter with a relative date","value":{"valid":true,"issues":[],"filter":{"createdAt":{"gte":"2026-08-31T20:00:00.000Z"}},"resolved_dates":[{"path":"filter.createdAt.gte","input":"start_of_month","value":"2026-08-31T20:00:00.000Z"}],"warnings":[],"notes":[],"conditions":1,"depth":1,"saved_filters":[],"timezone":"Asia/Dubai","count":120,"approximate":false}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The request itself is malformed (e.g. `filter` is not an object). A filter that breaks the rules is not an error: the answer is `valid: false` with `issues[]` (each with `path`, `message` and, when it has one, `reason`).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The request itself is malformed (e.g. `filter` is not an object). A filter that breaks the rules is not an error: the answer is `valid: false` with `issues[]` (each with `path`, `message` and, when it has one, `reason`).","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The request itself is malformed (e.g. `filter` is not an object). A filter that breaks the rules is not an error: the answer is `valid: false` with `issues[]` (each with `path`, `message` and, when it has one, `reason`).","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"502":{"description":"`upstream_error`: With `count: true`: the contacts service could not run this filter (`reason: filter_failed`). Simplify it.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_error":{"summary":"With `count: true`: the contacts service could not run this filter (`reason: filter_failed`). Simplify it.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_error","title":"A connected service answered unexpectedly","status":502,"detail":"With `count: true`: the contacts service could not run this filter (`reason: filter_failed`). Simplify it.","code":"upstream_error","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`service_unconfigured`: Advanced filters are switched off on this server (`reason: advanced_filter_disabled`). `upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"service_unconfigured":{"summary":"Advanced filters are switched off on this server (`reason: advanced_filter_disabled`).","value":{"type":"https://dev.wa-api.cloud/errors/service_unconfigured","title":"This feature is not set up here","status":503,"detail":"Advanced filters are switched off on this server (`reason: advanced_filter_disabled`).","code":"service_unconfigured","request_id":"req_01J8ZEXAMPLE0000000000000"}},"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: With `count: true`: counting took too long (`reason: query_timeout`). Narrow the filter.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"With `count: true`: counting took too long (`reason: query_timeout`). Narrow the filter.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"With `count: true`: counting took too long (`reason: query_timeout`). Narrow the filter.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_validate_contact_filter","x-platform-ops-path":"/ops/crm_validate_contact_filter","x-platform-group":"contacts","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The request itself is malformed (e.g. `filter` is not an object). A filter that breaks the rules is not an error: the answer is `valid: false` with `issues[]` (each with `path`, `message` and, when it has one, `reason`)."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_error","status":502,"when":"With `count: true`: the contacts service could not run this filter (`reason: filter_failed`). Simplify it."},{"code":"service_unconfigured","status":503,"when":"Advanced filters are switched off on this server (`reason: advanced_filter_disabled`)."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"With `count: true`: counting took too long (`reason: query_timeout`). Narrow the filter."}],"x-platform-examples":[{"name":"relative","summary":"Check a filter with a relative date","path":{},"query":{},"body":{"filter":{"createdAt":{"gte":"start_of_month"}},"count":true},"response":{"status":200,"body":{"valid":true,"issues":[],"filter":{"createdAt":{"gte":"2026-08-31T20:00:00.000Z"}},"resolved_dates":[{"path":"filter.createdAt.gte","input":"start_of_month","value":"2026-08-31T20:00:00.000Z"}],"warnings":[],"notes":[],"conditions":1,"depth":1,"saved_filters":[],"timezone":"Asia/Dubai","count":120,"approximate":false}}}]}},"/contacts/tag":{"post":{"operationId":"tagContacts","summary":"Add tags to contacts","description":"Adds tags to up to 500 contacts at once. Tag names that do not exist yet are created. Contacts keep their other tags; tagging twice is harmless.","tags":["tags"],"security":[{"api_key":["crm:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_ids":{"description":"Contact ids.","minItems":1,"maxItems":500,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Contact id (numeric id)."},"x-platform-picker":"contacts"},"tags":{"minItems":1,"maxItems":20,"type":"array","items":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}]},"description":"Tag names or ids. Names that do not exist yet are created.","x-platform-picker":"tags"}},"required":["contact_ids","tags"],"additionalProperties":false},"examples":{"optout":{"summary":"Mark a contact as opted out","value":{"contact_ids":["48213"],"tags":["opted-out"]}}}}}},"responses":{"200":{"description":"Counts and per-contact failures.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"requested":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"succeeded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["id","code","message"],"additionalProperties":false},"description":"Per-contact failures (first 50)."},"stopped_early":{"type":"boolean","description":"true when a fatal error (permission, rate limit) stopped the remaining batches; retry those ids."},"matched":{"description":"By filter: the contacts that matched when the change started (the ones changed).","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["requested","succeeded","failed","failures","stopped_early"]},"examples":{"optout":{"summary":"Mark a contact as opted out","value":{"requested":1,"succeeded":1,"failed":0,"failures":[],"stopped_early":false}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_tag_contacts","x-platform-ops-path":"/ops/crm_tag_contacts","x-platform-group":"tags","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Remove the tags again with **Remove tags from contacts**.","x-platform-events":["tag.created/1"],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"optout","summary":"Mark a contact as opted out","path":{},"query":{},"body":{"contact_ids":["48213"],"tags":["opted-out"]},"response":{"status":200,"body":{"requested":1,"succeeded":1,"failed":0,"failures":[],"stopped_early":false}}}]}},"/contacts/untag":{"post":{"operationId":"untagContacts","summary":"Remove tags from contacts","description":"Removes tags from up to 500 contacts. A contact without the tag is not an error; unknown tag names change nothing.","tags":["tags"],"security":[{"api_key":["crm:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_ids":{"description":"Contact ids.","minItems":1,"maxItems":500,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Contact id (numeric id)."},"x-platform-picker":"contacts"},"tags":{"minItems":1,"maxItems":20,"type":"array","items":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}]},"description":"Tag names or ids. Names that do not exist yet are created.","x-platform-picker":"tags"}},"required":["contact_ids","tags"],"additionalProperties":false},"examples":{"vip":{"summary":"Remove the VIP tag","value":{"contact_ids":["48213","48214"],"tags":["vip"]}}}}}},"responses":{"200":{"description":"Counts and per-contact failures.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"requested":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"succeeded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["id","code","message"],"additionalProperties":false},"description":"Per-contact failures (first 50)."},"stopped_early":{"type":"boolean","description":"true when a fatal error (permission, rate limit) stopped the remaining batches; retry those ids."},"matched":{"description":"By filter: the contacts that matched when the change started (the ones changed).","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["requested","succeeded","failed","failures","stopped_early"]},"examples":{"vip":{"summary":"Remove the VIP tag","value":{"requested":2,"succeeded":2,"failed":0,"failures":[],"stopped_early":false}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_untag_contacts","x-platform-ops-path":"/ops/crm_untag_contacts","x-platform-group":"tags","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Add the tags back with **Add tags to contacts**.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"vip","summary":"Remove the VIP tag","path":{},"query":{},"body":{"contact_ids":["48213","48214"],"tags":["vip"]},"response":{"status":200,"body":{"requested":2,"succeeded":2,"failed":0,"failures":[],"stopped_early":false}}}]}},"/groups/{group_id}/contacts":{"post":{"operationId":"addContactsToGroup","summary":"Add contacts to a group","description":"Adds up to 500 contacts to a group in one background job. Contacts keep their other groups; adding twice is harmless. Ids that are not in your workspace are skipped and listed in `failures`.\n\nThe change applies within seconds: check it with **Count contacts** and `group_ids`.","tags":["groups"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"group_id","in":"path","required":true,"description":"The group id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Contact group ids (1-20)."}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_ids":{"description":"Contact ids (1–500).","minItems":1,"maxItems":500,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Contact id (numeric id)."},"x-platform-picker":"contacts"}},"required":["contact_ids"],"additionalProperties":false},"examples":{"add":{"summary":"Add two contacts to a group","value":{"contact_ids":["48213","48214"]}}}}}},"responses":{"202":{"description":"Accepted: how many contacts the job took, and the ids it skipped.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"requested":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"accepted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Contacts handed to the background job."},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["id","code","message"],"additionalProperties":false}},"job_id":{"description":"The platform background job id; membership changes apply within seconds to minutes.","type":["string","null"]},"job_status":{"type":["string","null"]},"matched":{"description":"By filter: the contacts that matched when the change started (the ones handed to the job).","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["requested","accepted","failed","failures","job_id","job_status"]},"examples":{"add":{"summary":"Add two contacts to a group","value":{"requested":2,"accepted":2,"failed":0,"failures":[],"job_id":"88121","job_status":"pending"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. More than 500 contact ids, or the group does not exist.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. More than 500 contact ids, or the group does not exist.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. More than 500 contact ids, or the group does not exist.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_add_to_group","x-platform-ops-path":"/ops/crm_add_to_group","x-platform-group":"groups","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Remove them again with **Remove contacts from a group**.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. More than 500 contact ids, or the group does not exist."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"add","summary":"Add two contacts to a group","path":{"group_id":"6"},"query":{},"body":{"contact_ids":["48213","48214"]},"response":{"status":202,"body":{"requested":2,"accepted":2,"failed":0,"failures":[],"job_id":"88121","job_status":"pending"}}}]},"delete":{"operationId":"removeContactsFromGroup","summary":"Remove contacts from a group","description":"Removes up to 500 contacts from a group in one background job. **The contacts themselves are kept**. A contact that is not in the group is not an error; ids that are not in your workspace are listed in `failures`.\n\nSend the ids as a JSON body (`Content-Type: application/json`).","tags":["groups"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"group_id","in":"path","required":true,"description":"The group id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Contact group ids (1-20)."}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_ids":{"description":"Contact ids (1–500).","minItems":1,"maxItems":500,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Contact id (numeric id)."},"x-platform-picker":"contacts"}},"required":["contact_ids"],"additionalProperties":false},"examples":{"remove":{"summary":"Take a contact out of a group","value":{"contact_ids":["48213"]}}}}}},"responses":{"202":{"description":"Accepted: how many contacts the job took, and the ids it skipped.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"requested":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"accepted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Contacts handed to the background job."},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["id","code","message"],"additionalProperties":false}},"job_id":{"description":"The platform background job id; membership changes apply within seconds to minutes.","type":["string","null"]},"job_status":{"type":["string","null"]},"matched":{"description":"By filter: the contacts that matched when the change started (the ones handed to the job).","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["requested","accepted","failed","failures","job_id","job_status"]},"examples":{"remove":{"summary":"Take a contact out of a group","value":{"requested":1,"accepted":1,"failed":0,"failures":[],"job_id":"88122","job_status":"pending"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. More than 500 contact ids, or the group does not exist.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. More than 500 contact ids, or the group does not exist.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. More than 500 contact ids, or the group does not exist.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_remove_from_group","x-platform-ops-path":"/ops/crm_remove_from_group","x-platform-group":"groups","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Add them again with **Add contacts to a group**.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. More than 500 contact ids, or the group does not exist."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"remove","summary":"Take a contact out of a group","path":{"group_id":"6"},"query":{},"body":{"contact_ids":["48213"]},"response":{"status":202,"body":{"requested":1,"accepted":1,"failed":0,"failures":[],"job_id":"88122","job_status":"pending"}}}]}},"/groups/{group_id}":{"patch":{"operationId":"updateGroup","summary":"Rename a contact group","description":"Renames a group and/or changes its emoji. Its contacts are not affected. Pass at least one of `name` and `emoji`.","tags":["groups"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"group_id","in":"path","required":true,"description":"The group id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Group id (numeric id)."}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"New name.","type":"string","minLength":1,"maxLength":100},"emoji":{"description":"New emoji.","type":"string","minLength":1,"maxLength":10}},"additionalProperties":false},"examples":{"rename":{"summary":"Rename a group","value":{"name":"VIP (2026)"}}}}}},"responses":{"200":{"description":"The updated group.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"emoji":{"type":["string","null"]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","name","emoji"]},"examples":{"rename":{"summary":"Rename a group","value":{"id":"6","name":"VIP (2026)","emoji":"⭐"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No group with this id in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No group with this id in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No group with this id in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Another group already has this name (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Another group already has this name (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Another group already has this name (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_update_group","x-platform-ops-path":"/ops/crm_update_group","x-platform-group":"groups","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Send the old name and emoji back.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No group with this id in your workspace."},{"code":"conflict","status":409,"when":"Another group already has this name (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"rename","summary":"Rename a group","path":{"group_id":"6"},"query":{},"body":{"name":"VIP (2026)"},"response":{"status":200,"body":{"id":"6","name":"VIP (2026)","emoji":"⭐"}}}]},"delete":{"operationId":"deleteGroup","summary":"Delete a contact group","description":"Deletes one contact group. **Its contacts are kept**: they only leave the group.\n\nRefused with `409` (`reason: in_use`) while a scheduled broadcast or another feature still uses the group. Try it with `?dry_run=true` first.","tags":["groups"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"group_id","in":"path","required":true,"description":"The group id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Group id (`GET /v1/groups`) (numeric id)."}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"Deleted; the contacts are kept.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"deleted":{"type":"boolean"},"warning":{"type":["string","null"]},"contacts_kept":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","name","deleted","warning","contacts_kept"]},"examples":{"delete":{"summary":"Delete a group, keep its contacts","value":{"id":"6","name":"VIP customers","deleted":true,"contacts_kept":true,"warning":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No group with this id in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No group with this id in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No group with this id in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: The group is still in use, e.g. by a scheduled broadcast (`reason: in_use`). Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"The group is still in use, e.g. by a scheduled broadcast (`reason: in_use`). Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"The group is still in use, e.g. by a scheduled broadcast (`reason: in_use`). Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_delete_group","x-platform-ops-path":"/ops/crm_delete_group","x-platform-group":"groups","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":"delete","x-platform-undo":"Cannot be undone. Create the group again and add the contacts back.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No group with this id in your workspace."},{"code":"conflict","status":409,"when":"The group is still in use, e.g. by a scheduled broadcast (`reason: in_use`). Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"delete","summary":"Delete a group, keep its contacts","path":{"group_id":"6"},"query":{},"response":{"status":200,"body":{"id":"6","name":"VIP customers","deleted":true,"contacts_kept":true,"warning":null}}}]}},"/tags/{tag_id}":{"delete":{"operationId":"deleteTag","summary":"Delete a tag","description":"Deletes one tag. It is removed from every contact (or conversation) that has it; the contacts themselves are kept.\n\nRefused with `409` (`reason: in_use`) while a chatbot or automation still uses the tag. Try it with `?dry_run=true` first: the tag is looked up and checked, nothing is deleted.","tags":["tags"],"security":[{"api_key":["crm:write"]}],"parameters":[{"name":"tag_id","in":"path","required":true,"description":"The tag id.","schema":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Tag id (`GET /v1/tags`) (numeric id)."},"x-platform-picker":"tags"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"Deleted.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"deleted":{"type":"boolean"},"warning":{"type":["string","null"]},"type":{"type":["string","null"]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","name","deleted","warning","type"]},"examples":{"delete":{"summary":"Delete an old campaign tag","value":{"id":"51","name":"opted-out","type":"contact","deleted":true,"warning":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No tag with this id in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No tag with this id in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No tag with this id in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: The tag is still used by a chatbot or automation (`reason: in_use`). Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"The tag is still used by a chatbot or automation (`reason: in_use`). Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"The tag is still used by a chatbot or automation (`reason: in_use`). Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_delete_tag","x-platform-ops-path":"/ops/crm_delete_tag","x-platform-group":"tags","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":"delete","x-platform-undo":"Cannot be undone. Create the tag again and re-tag the contacts.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No tag with this id in your workspace."},{"code":"conflict","status":409,"when":"The tag is still used by a chatbot or automation (`reason: in_use`). Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"delete","summary":"Delete an old campaign tag","path":{"tag_id":"51"},"query":{},"response":{"status":200,"body":{"id":"51","name":"opted-out","type":"contact","deleted":true,"warning":null}}}]}},"/contacts/import":{"post":{"operationId":"importContacts","summary":"Import contacts in bulk","description":"Imports up to 1000 rows in one call. New phone numbers are created; existing ones are updated or skipped (`on_existing`). Invalid rows are skipped and reported.\n\nRun it with `?dry_run=true` first: it checks every row and changes nothing.","tags":["contacts"],"security":[{"api_key":["crm:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"phone":{"type":"string","minLength":1,"maxLength":40,"description":"Phone in international format, e.g. +971501234567."},"name":{"description":"Contact name.","type":"string","maxLength":255},"email":{"description":"Email (needs an \"email\" custom field).","type":"string","maxLength":255},"attributes":{"description":"Custom field values by field key (see `GET /v1/custom-fields`), e.g. {\"city\":\"Dubai\",\"vip\":true}. Values are coerced to the field type; null or \"\" clears a value.","type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":255},"additionalProperties":{"anyOf":[{"type":"string","maxLength":10000},{"type":"number"},{"type":"boolean"},{"maxItems":100,"type":"array","items":{"type":"string","maxLength":255}},{"type":"null"}]}}},"required":["phone"]},"description":"The contacts (1–1000)."},"group_ids":{"description":"Group ids.","maxItems":20,"type":"array","items":{"anyOf":[{"type":"string","pattern":"^[1-9]\\d{0,18}$"},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}],"description":"Group id (numeric id)."}},"tags":{"description":"Tag names or ids. Names that do not exist yet are created.","maxItems":20,"type":"array","items":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}]},"x-platform-picker":"tags"},"on_existing":{"default":"update","description":"What to do with numbers that already exist.","type":"string","enum":["update","skip"]}},"required":["rows"],"additionalProperties":false},"examples":{"two":{"summary":"Import two contacts into a group","value":{"rows":[{"phone":"+15555550123","name":"Jane Doe"},{"phone":"+15555550124","name":"Sam Lee"}],"tags":["import-sep"],"on_existing":"update"}}}}}},"responses":{"200":{"description":"Counts and per-row failures. On a dry run: how many rows are valid and every issue.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null in a dry run: known only when the change runs."},"updated":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"null in a dry run: known only when the change runs."},"skipped":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Existing contacts left untouched (onExisting \"skip\")."},"invalid":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Rows rejected by validation before anything was written."},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failures":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"type":"string"}},"required":["row","code","message"],"additionalProperties":false},"description":"Invalid and failed rows (first 50)."},"stopped_early":{"type":"boolean","description":"true when the plan limit, a permission error, a rate limit or the time limit stopped the import; the rows after it were not written."},"group_job_id":{"type":["string","null"]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."},"valid":{"type":"integer","description":"Dry run: rows that passed every check (they would be created or updated)."},"note":{"type":"string","description":"Dry run: what the preview cannot tell yet."}},"required":["total","created","updated","skipped","invalid","failed","failures","stopped_early","group_job_id"]},"examples":{"two":{"summary":"Import two contacts into a group","value":{"total":2,"created":0,"updated":0,"skipped":0,"invalid":0,"failed":0,"failures":[],"stopped_early":false,"dry_run":true,"group_job_id":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: Your plan contact limit is reached. `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"Your plan contact limit is reached.","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"Your plan contact limit is reached.","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"crm_import_contacts","x-platform-ops-path":"/ops/crm_import_contacts","x-platform-group":"contacts","x-platform-scope":"crm:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"required","x-platform-dry-run":"native","x-platform-destructive-verb":null,"x-platform-undo":"No bulk undo. Delete created contacts one by one if needed.","x-platform-events":["contact.created/1","contact.updated/1","contact.import.completed/1"],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"Your plan contact limit is reached."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"two","summary":"Import two contacts into a group","path":{},"query":{"dry_run":true},"body":{"rows":[{"phone":"+15555550123","name":"Jane Doe"},{"phone":"+15555550124","name":"Sam Lee"}],"tags":["import-sep"],"on_existing":"update"},"response":{"status":200,"body":{"total":2,"created":0,"updated":0,"skipped":0,"invalid":0,"failed":0,"failures":[],"stopped_early":false,"dry_run":true,"group_job_id":null}}}]}},"/quick-messages":{"get":{"operationId":"listQuickMessages","summary":"List quick messages","description":"Lists the quick messages (saved replies your team inserts in the inbox by typing `/code`) this key's user can see. Favourites first, then newest.","tags":["quick-messages"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"search","in":"query","required":false,"description":"Code contains this text.","schema":{"description":"Code contains this text.","type":"string","maxLength":100}},{"name":"type","in":"query","required":false,"description":"Only this message type.","schema":{"description":"Only this message type.","type":"string","enum":["TEXT","IMAGE","VIDEO","DOCUMENT","AUDIO","TEMPLATE","INTERACTIVE","LOCATION"]}},{"name":"favorites_only","in":"query","required":false,"description":"`true` = favourites only.","schema":{"description":"`true` = favourites only.","type":"boolean"}},{"name":"channel_id","in":"query","required":false,"description":"Leave out template and flow quick messages that cannot be sent on this channel.","schema":{"description":"Leave out template and flow quick messages that cannot be sent on this channel.","type":"string","maxLength":64},"x-platform-picker":"channels"},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of quick messages.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"description":"Shortcut agents type after \"/\" in the inbox.","type":["string","null"]},"title":{"type":["string","null"]},"type":{"description":"TEXT, IMAGE, VIDEO, DOCUMENT, TEMPLATE, INTERACTIVE …","type":["string","null"]},"text":{"description":"Text body, or the media caption.","type":["string","null"]},"media_url":{"type":["string","null"]},"template_name":{"type":["string","null"]},"visibility":{"type":["string","null"]},"team_id":{"type":["string","null"]},"favorite":{"type":"boolean"},"can_edit":{"type":"boolean"},"updated_at":{"type":["string","null"]}},"required":["id","code","title","type","text","media_url","template_name","visibility","team_id","favorite","can_edit","updated_at"],"additionalProperties":false}},"total":{"type":"number"},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","next_cursor"]},"examples":{"all":{"summary":"All quick messages","value":{"data":[{"id":"12","code":"thanks","title":"Thank you","type":"TEXT","text":"Thanks for your order, {{contact.name}}!","media_url":null,"template_name":null,"visibility":"company","team_id":null,"favorite":true,"can_edit":true,"updated_at":"2026-09-02T10:00:00Z"}],"next_cursor":null,"total":1}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_list_quick_messages","x-platform-ops-path":"/ops/messaging_list_quick_messages","x-platform-group":"quick-messages","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"all","summary":"All quick messages","path":{},"query":{},"response":{"status":200,"body":{"data":[{"id":"12","code":"thanks","title":"Thank you","type":"TEXT","text":"Thanks for your order, {{contact.name}}!","media_url":null,"template_name":null,"visibility":"company","team_id":null,"favorite":true,"can_edit":true,"updated_at":"2026-09-02T10:00:00Z"}],"next_cursor":null,"total":1}}}]},"post":{"operationId":"createQuickMessage","summary":"Create a quick message","description":"Creates a quick message your team can insert in the inbox by typing `/code`. `TEXT` needs `text`; `IMAGE`, `VIDEO` and `DOCUMENT` need a public `media_url` (`text` becomes the caption).\n\nIt is private to the key's user unless `visibility` is `team` (with `team_id`) or `company`. The `code` must be unique in your workspace.","tags":["quick-messages"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":60,"pattern":"^\\S+$","description":"Shortcut code, unique, no spaces, e.g. `thanks`."},"title":{"type":"string","minLength":1,"maxLength":120,"description":"Title shown in the picker."},"description":{"description":"A note for your team.","type":"string","maxLength":500},"type":{"default":"TEXT","description":"`TEXT` (default), `IMAGE`, `VIDEO` or `DOCUMENT`.","type":"string","enum":["TEXT","IMAGE","VIDEO","DOCUMENT"]},"text":{"description":"The message (`TEXT`), or the caption of a media message. Variables such as `{{contact.name}}` are allowed.","type":"string","maxLength":4096},"media_url":{"description":"Public https URL of the file (media types).","type":"string","maxLength":2000,"format":"uri"},"file_name":{"description":"`DOCUMENT`: the file name the customer sees.","type":"string","maxLength":200},"visibility":{"description":"`private` (default), `team` or `company`.","type":"string","enum":["private","team","company"]},"team_id":{"description":"The team, with `visibility: team`.","type":"string","maxLength":20}},"required":["code","title"],"additionalProperties":false},"examples":{"thanks":{"summary":"A thank-you reply for the whole team","value":{"code":"thanks","title":"Thank you","text":"Thanks for your order, {{contact.name}}!","visibility":"company"}}}}}},"responses":{"201":{"description":"The new quick message.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"code":{"description":"Shortcut agents type after \"/\" in the inbox.","type":["string","null"]},"title":{"type":["string","null"]},"type":{"description":"TEXT, IMAGE, VIDEO, DOCUMENT, TEMPLATE, INTERACTIVE …","type":["string","null"]},"text":{"description":"Text body, or the media caption.","type":["string","null"]},"media_url":{"type":["string","null"]},"template_name":{"type":["string","null"]},"visibility":{"type":["string","null"]},"team_id":{"type":["string","null"]},"favorite":{"type":"boolean"},"can_edit":{"type":"boolean"},"updated_at":{"type":["string","null"]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","code","title","type","text","media_url","template_name","visibility","team_id","favorite","can_edit","updated_at"]},"examples":{"thanks":{"summary":"A thank-you reply for the whole team","value":{"id":"12","code":"thanks","title":"Thank you","type":"TEXT","text":"Thanks for your order, {{contact.name}}!","media_url":null,"template_name":null,"visibility":"company","team_id":null,"favorite":false,"can_edit":true,"updated_at":"2026-09-02T10:00:00Z"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The code is already taken, or a field the type needs is missing. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The code is already taken, or a field the type needs is missing. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The code is already taken, or a field the type needs is missing. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_create_quick_message","x-platform-ops-path":"/ops/messaging_create_quick_message","x-platform-group":"quick-messages","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"required","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Delete it with **Delete a quick message**.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The code is already taken, or a field the type needs is missing. Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"thanks","summary":"A thank-you reply for the whole team","path":{},"query":{},"body":{"code":"thanks","title":"Thank you","text":"Thanks for your order, {{contact.name}}!","visibility":"company"},"response":{"status":201,"body":{"id":"12","code":"thanks","title":"Thank you","type":"TEXT","text":"Thanks for your order, {{contact.name}}!","media_url":null,"template_name":null,"visibility":"company","team_id":null,"favorite":false,"can_edit":true,"updated_at":"2026-09-02T10:00:00Z"}}}]}},"/quick-messages/{quick_message_id}":{"patch":{"operationId":"updateQuickMessage","summary":"Update a quick message","description":"Changes only the fields you pass. The type cannot change: delete it and create a new one instead. Only `TEXT`, `IMAGE`, `VIDEO` and `DOCUMENT` quick messages can be edited here.","tags":["quick-messages"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"name":"quick_message_id","in":"path","required":true,"description":"The quick message id.","schema":{"description":"Quick message id.","anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"description":"New shortcut code (unique, no spaces).","type":"string","minLength":1,"maxLength":60,"pattern":"^\\S+$"},"title":{"description":"New title.","type":"string","minLength":1,"maxLength":120},"description":{"description":"A note for your team.","type":"string","maxLength":500},"text":{"description":"The message (`TEXT`), or the caption of a media message.","type":"string","maxLength":4096},"media_url":{"description":"Public https URL of a new file (media types).","type":"string","maxLength":2000,"format":"uri"},"file_name":{"description":"`DOCUMENT`: the file name the customer sees.","type":"string","maxLength":200},"visibility":{"description":"`private`, `team` or `company`.","type":"string","enum":["private","team","company"]},"team_id":{"description":"The team, with `visibility: team`.","type":"string","maxLength":20}},"additionalProperties":false},"examples":{"retitle":{"summary":"Change the wording","value":{"text":"Thank you for your order, {{contact.name}}!"}}}}}},"responses":{"200":{"description":"The updated quick message.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"code":{"description":"Shortcut agents type after \"/\" in the inbox.","type":["string","null"]},"title":{"type":["string","null"]},"type":{"description":"TEXT, IMAGE, VIDEO, DOCUMENT, TEMPLATE, INTERACTIVE …","type":["string","null"]},"text":{"description":"Text body, or the media caption.","type":["string","null"]},"media_url":{"type":["string","null"]},"template_name":{"type":["string","null"]},"visibility":{"type":["string","null"]},"team_id":{"type":["string","null"]},"favorite":{"type":"boolean"},"can_edit":{"type":"boolean"},"updated_at":{"type":["string","null"]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","code","title","type","text","media_url","template_name","visibility","team_id","favorite","can_edit","updated_at"]},"examples":{"retitle":{"summary":"Change the wording","value":{"id":"12","code":"thanks","title":"Thank you","type":"TEXT","text":"Thank you for your order, {{contact.name}}!","media_url":null,"template_name":null,"visibility":"company","team_id":null,"favorite":false,"can_edit":true,"updated_at":"2026-09-03T10:00:00Z"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The key's user is not allowed to edit this quick message. `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The key's user is not allowed to edit this quick message.","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The key's user is not allowed to edit this quick message.","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No quick message with this id that the key's user can see.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No quick message with this id that the key's user can see.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No quick message with this id that the key's user can see.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_update_quick_message","x-platform-ops-path":"/ops/messaging_update_quick_message","x-platform-group":"quick-messages","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Send the old values back.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The key's user is not allowed to edit this quick message."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No quick message with this id that the key's user can see."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"retitle","summary":"Change the wording","path":{"quick_message_id":"12"},"query":{},"body":{"text":"Thank you for your order, {{contact.name}}!"},"response":{"status":200,"body":{"id":"12","code":"thanks","title":"Thank you","type":"TEXT","text":"Thank you for your order, {{contact.name}}!","media_url":null,"template_name":null,"visibility":"company","team_id":null,"favorite":false,"can_edit":true,"updated_at":"2026-09-03T10:00:00Z"}}}]},"delete":{"operationId":"deleteQuickMessage","summary":"Delete a quick message","description":"Deletes one quick message for good: your team loses its `/code` shortcut.","tags":["quick-messages"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"name":"quick_message_id","in":"path","required":true,"description":"The quick message id.","schema":{"description":"Quick message id.","anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"Deleted.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"deleted":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","deleted"]},"examples":{"delete":{"summary":"Delete a quick message","value":{"id":"12","deleted":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No quick message with this id that the key's user can see.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No quick message with this id that the key's user can see.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No quick message with this id that the key's user can see.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_delete_quick_message","x-platform-ops-path":"/ops/messaging_delete_quick_message","x-platform-group":"quick-messages","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":"delete","x-platform-undo":"Cannot be undone. Create it again.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No quick message with this id that the key's user can see."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"delete","summary":"Delete a quick message","path":{"quick_message_id":"12"},"query":{},"response":{"status":200,"body":{"id":"12","deleted":true}}}]}},"/templates":{"get":{"operationId":"listTemplates","summary":"List WhatsApp templates","description":"Lists your WhatsApp message templates with their review status, newest first. Only `APPROVED` templates can be sent.","tags":["templates"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Only this review status.","schema":{"description":"Only this review status.","type":"string","enum":["APPROVED","PENDING","REJECTED","PAUSED","DISABLED","IN_APPEAL","ARCHIVED","PENDING_DELETION","DELETED"]}},{"name":"category","in":"query","required":false,"description":"Only this category.","schema":{"description":"Only this category.","type":"string","enum":["MARKETING","UTILITY","AUTHENTICATION"]}},{"name":"language","in":"query","required":false,"description":"Language code, e.g. `en_US`.","schema":{"description":"Language code, e.g. `en_US`.","type":"string","maxLength":20}},{"name":"search","in":"query","required":false,"description":"Name contains.","schema":{"description":"Name contains.","type":"string","maxLength":100}},{"name":"channel_id","in":"query","required":false,"description":"Templates of the WhatsApp account behind this channel.","schema":{"description":"Templates of the WhatsApp account behind this channel.","type":"string","maxLength":64},"x-platform-picker":"channels"},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of templates.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":["string","null"]},"category":{"type":["string","null"]},"sub_category":{"type":["string","null"]},"status":{"description":"Meta review status: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, IN_APPEAL, ARCHIVED …","type":["string","null"]},"rejection_reason":{"description":"Meta's reason when REJECTED/PAUSED (verbatim), else null.","type":["string","null"]},"body_preview":{"type":["string","null"]},"variable_count":{"type":"number","description":"Body variables to supply when sending."},"header_format":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","name","language","category","sub_category","status","rejection_reason","body_preview","variable_count","header_format","updated_at"],"additionalProperties":false}},"total":{"type":"number","description":"Matches before the language filter."},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","next_cursor"]},"examples":{"approved":{"summary":"Approved templates","value":{"data":[{"id":"9120","name":"order_shipped","language":"en_US","category":"UTILITY","status":"APPROVED","rejection_reason":null,"body_preview":"Hi {{1}}, your order {{2}} is on its way. Track it here: {{3}}","variable_count":3,"header_format":null,"updated_at":"2026-09-12T10:00:00Z","sub_category":null}],"next_cursor":null,"total":1}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_list_templates","x-platform-ops-path":"/ops/messaging_list_templates","x-platform-group":"templates","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"approved","summary":"Approved templates","path":{},"query":{"status":"APPROVED"},"response":{"status":200,"body":{"data":[{"id":"9120","name":"order_shipped","language":"en_US","category":"UTILITY","status":"APPROVED","rejection_reason":null,"body_preview":"Hi {{1}}, your order {{2}} is on its way. Track it here: {{3}}","variable_count":3,"header_format":null,"updated_at":"2026-09-12T10:00:00Z","sub_category":null}],"next_cursor":null,"total":1}}}]},"post":{"operationId":"createTemplate","summary":"Create a WhatsApp template","description":"Checks a template draft against WhatsApp's rules, then **submits it to WhatsApp for review**. The submission is visible to WhatsApp and counts against your account's template limits, so it needs `Api-Confirm: submit`. Review takes minutes to hours: read the template with **Get a template** until it is `APPROVED` or `REJECTED`.\n\n- `name`: lower-case letters, digits and `_`; the same name can exist once per language. A name that exists in that language is refused with `409` (`reason: duplicate`).\n- `language`: a WhatsApp language code such as `en`, `en_US` or `pt_BR`.\n- A draft that breaks a rule is refused with `400` (`reason: template_rules`); `errors[]` names each field and rule. **Check a template draft** explains every rule with a fix.\n- An IMAGE, VIDEO or DOCUMENT header needs a sample handle from **Upload a template header sample**.\n\nRun it with `?dry_run=true` first: every check runs and `payload_preview` shows exactly what would be submitted, but nothing is.","tags":["templates"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string","maxLength":1000,"description":"Template name: lowercase letters, digits, underscores (e.g. order_shipped_v2)."},"language":{"type":"string","maxLength":20,"description":"Meta language code, e.g. en, en_US, ar, hi, pt_BR."},"category":{"type":"string","maxLength":40,"description":"MARKETING | UTILITY | AUTHENTICATION."},"header":{"description":"Optional header.","type":"object","properties":{"format":{"type":"string","enum":["TEXT","IMAGE","VIDEO","DOCUMENT","LOCATION"],"description":"TEXT | IMAGE | VIDEO | DOCUMENT | LOCATION."},"text":{"type":"string","maxLength":1000,"description":"TEXT header: ≤ 60 chars, at most one {{1}}."},"example":{"type":"string","maxLength":1000,"description":"TEXT header with {{1}}: its sample value."},"media_handle":{"type":"string","maxLength":4000,"description":"IMAGE/VIDEO/DOCUMENT header: the Meta upload handle used as the sample (`POST /v1/templates/samples`)."}},"required":["format"]},"body":{"default":{},"description":"Body.","type":"object","properties":{"text":{"type":"string","maxLength":5000,"description":"Body text (≤ 1024 chars) with {{1}}, {{2}} … variables. Omit for AUTHENTICATION (Meta fixes it)."},"examples":{"description":"One sample per body variable, in order ({{1}} first).","maxItems":100,"type":"array","items":{"type":"string","maxLength":1000,"description":"Sample value."}},"add_security_recommendation":{"description":"AUTHENTICATION only: append \"For your security, do not share this code.\"","type":"boolean"}}},"footer":{"description":"Optional footer.","type":"object","properties":{"text":{"type":"string","maxLength":1000,"description":"Footer text (≤ 60 chars, no variables)."},"code_expiration_minutes":{"description":"AUTHENTICATION only: code expiry shown in the footer (1-90).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"buttons":{"description":"Buttons in display order (≤ 10).","maxItems":30,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE","FLOW","VOICE_CALL","OTP"],"description":"QUICK_REPLY | URL | PHONE_NUMBER | COPY_CODE | FLOW | VOICE_CALL | OTP."},"text":{"type":"string","maxLength":200,"description":"Button label (≤ 25 chars). Not used for COPY_CODE."},"url":{"type":"string","maxLength":4000,"description":"URL buttons: https URL; for a dynamic URL end it with {{1}} (e.g. https://shop.example/track/{{1}})."},"url_example":{"type":"string","maxLength":4000,"description":"Dynamic URL buttons: a full example URL with the variable filled in."},"phone_number":{"type":"string","maxLength":64,"description":"PHONE_NUMBER buttons: E.164 number, e.g. +971501234567."},"coupon_code":{"type":"string","maxLength":64,"description":"COPY_CODE buttons: the coupon code to copy (≤ 20 chars)."},"flow_id":{"type":"string","maxLength":64,"description":"FLOW buttons: the WhatsApp flow id."},"flow_action":{"description":"FLOW buttons: NAVIGATE (default) or DATA_EXCHANGE for endpoint flows.","type":"string","enum":["NAVIGATE","DATA_EXCHANGE"]},"navigate_screen":{"type":"string","maxLength":200,"description":"FLOW buttons with NAVIGATE: the first screen id."},"otp_type":{"description":"OTP buttons: COPY_CODE (default), ONE_TAP or ZERO_TAP.","type":"string","enum":["COPY_CODE","ONE_TAP","ZERO_TAP"]},"supported_apps":{"description":"ONE_TAP / ZERO_TAP OTP buttons: your Android app(s).","maxItems":5,"type":"array","items":{"type":"object","properties":{"package_name":{"type":"string","maxLength":255,"description":"Android package name."},"signature_hash":{"type":"string","maxLength":64,"description":"App signing key hash."}},"required":["package_name","signature_hash"]}}},"required":["type"],"description":"One button."}},"limited_time_offer":{"description":"Limited-time offer (MARKETING; needs a COPY_CODE button).","type":"object","properties":{"text":{"type":"string","maxLength":200,"description":"Offer text shown on the chip (≤ 16 chars)."},"has_expiration":{"description":"Show a countdown (the expiry is set when sending).","type":"boolean"}},"required":["text"]},"carousel":{"description":"Media carousel (MARKETING): the body is the message above the cards; no top-level header, footer or buttons.","type":"object","properties":{"cards":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"header_format":{"type":"string","enum":["IMAGE","VIDEO"],"description":"Card media type (the same on every card)."},"media_handle":{"type":"string","maxLength":4000,"description":"Meta upload handle for the card media (`POST /v1/templates/samples`)."},"body":{"description":"Card text.","type":"object","properties":{"text":{"type":"string","maxLength":1000,"description":"Card text (≤ 160 chars, {{1}}… allowed)."},"examples":{"description":"One sample per card variable.","maxItems":20,"type":"array","items":{"type":"string","maxLength":1000,"description":"Sample value."}}},"required":["text"]},"buttons":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE","FLOW","VOICE_CALL","OTP"],"description":"QUICK_REPLY | URL | PHONE_NUMBER | COPY_CODE | FLOW | VOICE_CALL | OTP."},"text":{"type":"string","maxLength":200,"description":"Button label (≤ 25 chars). Not used for COPY_CODE."},"url":{"type":"string","maxLength":4000,"description":"URL buttons: https URL; for a dynamic URL end it with {{1}} (e.g. https://shop.example/track/{{1}})."},"url_example":{"type":"string","maxLength":4000,"description":"Dynamic URL buttons: a full example URL with the variable filled in."},"phone_number":{"type":"string","maxLength":64,"description":"PHONE_NUMBER buttons: E.164 number, e.g. +971501234567."},"coupon_code":{"type":"string","maxLength":64,"description":"COPY_CODE buttons: the coupon code to copy (≤ 20 chars)."},"flow_id":{"type":"string","maxLength":64,"description":"FLOW buttons: the WhatsApp flow id."},"flow_action":{"description":"FLOW buttons: NAVIGATE (default) or DATA_EXCHANGE for endpoint flows.","type":"string","enum":["NAVIGATE","DATA_EXCHANGE"]},"navigate_screen":{"type":"string","maxLength":200,"description":"FLOW buttons with NAVIGATE: the first screen id."},"otp_type":{"description":"OTP buttons: COPY_CODE (default), ONE_TAP or ZERO_TAP.","type":"string","enum":["COPY_CODE","ONE_TAP","ZERO_TAP"]},"supported_apps":{"description":"ONE_TAP / ZERO_TAP OTP buttons: your Android app(s).","maxItems":5,"type":"array","items":{"type":"object","properties":{"package_name":{"type":"string","maxLength":255,"description":"Android package name."},"signature_hash":{"type":"string","maxLength":64,"description":"App signing key hash."}},"required":["package_name","signature_hash"]}}},"required":["type"],"description":"One button."},"description":"1-2 buttons (QUICK_REPLY, URL, PHONE_NUMBER), the same layout on every card."}},"required":["header_format","media_handle","buttons"]},"description":"2-10 cards."}},"required":["cards"]}},"required":["name","language","category"],"description":"The draft: name, language, category, optional header, body, footer and buttons."},"business_account_id":{"description":"The WhatsApp account to create it in. Needed only when your workspace has several.","type":"string","maxLength":64},"channel_id":{"description":"Instead of `business_account_id`: a connected WhatsApp channel; its account is used.","type":"string","maxLength":64,"x-platform-picker":"channels"},"allow_category_change":{"description":"Let WhatsApp change the category instead of rejecting the template (default `true`).","type":"boolean"}},"required":["template"],"additionalProperties":false},"examples":{"pickup":{"summary":"An order-ready utility template","value":{"template":{"name":"order_ready","language":"en_US","category":"UTILITY","body":{"text":"Hi {{1}}, your order {{2}} is ready for pickup today.","examples":["Jane","#1001"]},"footer":{"text":"Reply STOP to opt out"},"buttons":[{"type":"QUICK_REPLY","text":"On my way"}]}}}}}}},"responses":{"201":{"description":"Submitted for review (or, on a dry run, the checked draft and the exact payload).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"submitted":{"type":"boolean","description":"true when the template was sent to Meta for review."},"id":{"description":"Template id when submitted.","type":["string","null"]},"name":{"type":"string"},"language":{"type":"string"},"category":{"type":["string","null"]},"status":{"type":["string","null"]},"business_account_id":{"type":"string"},"business_account_name":{"type":"string","description":"The account, by name — say it to the user."},"lint":{"type":"object","properties":{"valid":{"type":"boolean","description":"true when there are no errors (warnings may remain)."},"errors":{"type":"number"},"warnings":{"type":"number"},"issues":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"severity":{"type":"string","enum":["error","warning","info"]},"path":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"}},"required":["rule","severity","path","message","fix"],"additionalProperties":false}},"variables":{"type":"object","properties":{"header":{"type":"number"},"body":{"type":"number"}},"required":["header","body"],"additionalProperties":false},"preview":{"description":"Body with samples filled in.","type":["string","null"]}},"required":["valid","errors","warnings","issues","variables","preview"],"additionalProperties":false},"payload_preview":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":"The exact components that are (or would be) submitted."},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["submitted","id","name","language","category","status","business_account_id","business_account_name","lint","payload_preview"]},"examples":{"pickup":{"summary":"An order-ready utility template","value":{"submitted":false,"id":null,"name":"order_ready","language":"en_US","category":"UTILITY","status":null,"business_account_id":"4410","business_account_name":"Main WhatsApp","lint":{"valid":true,"errors":0,"warnings":0,"issues":[],"variables":{"header":0,"body":2},"preview":null},"payload_preview":[{"type":"BODY","text":"Hi {{1}}, your order {{2}} is ready for pickup today.","example":{"body_text":[["Jane","#1001"]]}},{"type":"FOOTER","text":"Reply STOP to opt out"},{"type":"BUTTONS","buttons":[{"type":"QUICK_REPLY","text":"On my way"}]}],"dry_run":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The draft breaks a template rule (`reason: template_rules`), or the workspace has several WhatsApp accounts and none was chosen (`reason: account_ambiguous`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The draft breaks a template rule (`reason: template_rules`), or the workspace has several WhatsApp accounts and none was chosen (`reason: account_ambiguous`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The draft breaks a template rule (`reason: template_rules`), or the workspace has several WhatsApp accounts and none was chosen (`reason: account_ambiguous`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: The channel or WhatsApp account does not exist in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"The channel or WhatsApp account does not exist in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"The channel or WhatsApp account does not exist in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: A template with this name already exists in this language (`reason: duplicate`), or no WhatsApp account is connected (`reason: channel_not_connected`). Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"A template with this name already exists in this language (`reason: duplicate`), or no WhatsApp account is connected (`reason: channel_not_connected`). Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"A template with this name already exists in this language (`reason: duplicate`), or no WhatsApp account is connected (`reason: channel_not_connected`). Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: submit` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: submit` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: submit` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"502":{"description":"`upstream_error`: WhatsApp refused the submission.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_error":{"summary":"WhatsApp refused the submission.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_error","title":"A connected service answered unexpectedly","status":502,"detail":"WhatsApp refused the submission.","code":"upstream_error","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_create_template","x-platform-ops-path":"/ops/messaging_create_template","x-platform-group":"templates","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"required","x-platform-dry-run":"native","x-platform-destructive-verb":"submit","x-platform-undo":"A submission cannot be withdrawn. Archive the template with **Archive templates** once it is reviewed.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The draft breaks a template rule (`reason: template_rules`), or the workspace has several WhatsApp accounts and none was chosen (`reason: account_ambiguous`). Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"The channel or WhatsApp account does not exist in your workspace."},{"code":"conflict","status":409,"when":"A template with this name already exists in this language (`reason: duplicate`), or no WhatsApp account is connected (`reason: channel_not_connected`). Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: submit` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_error","status":502,"when":"WhatsApp refused the submission."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"pickup","summary":"An order-ready utility template","path":{},"query":{"dry_run":true},"body":{"template":{"name":"order_ready","language":"en_US","category":"UTILITY","body":{"text":"Hi {{1}}, your order {{2}} is ready for pickup today.","examples":["Jane","#1001"]},"footer":{"text":"Reply STOP to opt out"},"buttons":[{"type":"QUICK_REPLY","text":"On my way"}]}},"response":{"status":201,"body":{"submitted":false,"id":null,"name":"order_ready","language":"en_US","category":"UTILITY","status":null,"business_account_id":"4410","business_account_name":"Main WhatsApp","lint":{"valid":true,"errors":0,"warnings":0,"issues":[],"variables":{"header":0,"body":2},"preview":null},"payload_preview":[{"type":"BODY","text":"Hi {{1}}, your order {{2}} is ready for pickup today.","example":{"body_text":[["Jane","#1001"]]}},{"type":"FOOTER","text":"Reply STOP to opt out"},{"type":"BUTTONS","buttons":[{"type":"QUICK_REPLY","text":"On my way"}]}],"dry_run":true}}}]}},"/templates/{template_id}":{"get":{"operationId":"getTemplate","summary":"Get a template","description":"Returns one template in full: header, body with each `{{n}}` variable and its sample, footer, buttons and review status. Read this before sending, to know how many variables to pass.","tags":["templates"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"template_id","in":"path","required":true,"description":"The template id.","schema":{"description":"Template id from `GET /v1/templates`.","anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"x-platform-picker":"templates"},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The template.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":["string","null"]},"category":{"type":["string","null"]},"sub_category":{"type":["string","null"]},"status":{"description":"Meta review status: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, IN_APPEAL, ARCHIVED …","type":["string","null"]},"rejection_reason":{"description":"Meta's reason when REJECTED/PAUSED (verbatim), else null.","type":["string","null"]},"body_preview":{"type":["string","null"]},"variable_count":{"type":"number","description":"Body variables to supply when sending."},"header_format":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"header":{"anyOf":[{"type":"object","properties":{"format":{"type":["string","null"]},"text":{"type":["string","null"]},"variables":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number","description":"1-based position ({{index}})."},"sample":{"type":["string","null"]}},"required":["index","sample"],"additionalProperties":false}},"media_sample":{"type":["string","null"]}},"required":["format","text","variables","media_sample"],"additionalProperties":false},{"type":"null"}]},"body":{"anyOf":[{"type":"object","properties":{"text":{"type":["string","null"]},"variables":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number","description":"1-based position ({{index}})."},"sample":{"type":["string","null"]}},"required":["index","sample"],"additionalProperties":false}}},"required":["text","variables"],"additionalProperties":false},{"type":"null"}]},"footer":{"type":["string","null"]},"buttons":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number"},"type":{"type":"string"},"text":{"type":["string","null"]},"url":{"type":["string","null"]},"dynamic_url":{"type":"boolean","description":"true when the URL ends with {{1}}: a suffix is required when sending."},"url_example":{"type":["string","null"]},"phone_number":{"type":["string","null"]},"coupon_code":{"type":["string","null"]},"flow_id":{"type":["string","null"]}},"required":["index","type","text","url","dynamic_url","url_example","phone_number","coupon_code","flow_id"],"additionalProperties":false}},"carousel_cards":{"type":"number"},"limited_time_offer":{"anyOf":[{"type":"object","properties":{"text":{"type":["string","null"]},"has_expiration":{"type":"boolean"}},"required":["text","has_expiration"],"additionalProperties":false},{"type":"null"}]},"meta_errors":{"anyOf":[{},{"type":"null"}],"description":"Last Meta error payload stored for this template, if any."},"created_at":{"type":["string","null"]}},"required":["id","name","language","category","sub_category","status","rejection_reason","body_preview","variable_count","header_format","updated_at","header","body","footer","buttons","carousel_cards","limited_time_offer","meta_errors","created_at"]},"examples":{"shipped":{"summary":"The order-shipped template","value":{"id":"9120","name":"order_shipped","language":"en_US","category":"UTILITY","status":"APPROVED","rejection_reason":null,"body_preview":"Hi {{1}}, your order {{2}} is on its way. Track it here: {{3}}","variable_count":3,"header_format":null,"updated_at":"2026-09-12T10:00:00Z","header":null,"body":{"text":"Hi {{1}}, your order {{2}} is on its way. Track it here: {{3}}","variables":[{"index":1,"sample":"Jane"},{"index":2,"sample":"#1001"},{"index":3,"sample":"https://track.example.com/1001"}]},"footer":"Reply STOP to opt out","buttons":[],"created_at":"2026-09-01T09:00:00Z","sub_category":null,"carousel_cards":0,"limited_time_offer":null,"meta_errors":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No template with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No template with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No template with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_get_template","x-platform-ops-path":"/ops/messaging_get_template","x-platform-group":"templates","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No template with this id."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"shipped","summary":"The order-shipped template","path":{"template_id":"9120"},"query":{},"response":{"status":200,"body":{"id":"9120","name":"order_shipped","language":"en_US","category":"UTILITY","status":"APPROVED","rejection_reason":null,"body_preview":"Hi {{1}}, your order {{2}} is on its way. Track it here: {{3}}","variable_count":3,"header_format":null,"updated_at":"2026-09-12T10:00:00Z","header":null,"body":{"text":"Hi {{1}}, your order {{2}} is on its way. Track it here: {{3}}","variables":[{"index":1,"sample":"Jane"},{"index":2,"sample":"#1001"},{"index":3,"sample":"https://track.example.com/1001"}]},"footer":"Reply STOP to opt out","buttons":[],"created_at":"2026-09-01T09:00:00Z","sub_category":null,"carousel_cards":0,"limited_time_offer":null,"meta_errors":null}}}]},"put":{"operationId":"updateTemplate","summary":"Edit a WhatsApp template","description":"Replaces a template's content (header, body, footer, buttons) and **resubmits it to WhatsApp for review**: it goes back to `PENDING` and cannot be sent until approved again, so it needs `Api-Confirm: submit`.\n\n- `name` and `language` must stay the same as the template's; to change them, create a new template.\n- Only `APPROVED`, `REJECTED` or `PAUSED` templates can be edited (`409`, `reason: not_editable`, otherwise). WhatsApp limits how often an approved template can be edited, and never lets its category change.\n- A draft that breaks a rule is refused with `400` (`reason: template_rules`).\n\nTry it with `?dry_run=true`: the template is read and the draft checked, nothing is submitted.","tags":["templates"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"name":"template_id","in":"path","required":true,"description":"The template id.","schema":{"description":"Template id.","anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"x-platform-picker":"templates"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string","maxLength":1000,"description":"Template name: lowercase letters, digits, underscores (e.g. order_shipped_v2)."},"language":{"type":"string","maxLength":20,"description":"Meta language code, e.g. en, en_US, ar, hi, pt_BR."},"category":{"type":"string","maxLength":40,"description":"MARKETING | UTILITY | AUTHENTICATION."},"header":{"description":"Optional header.","type":"object","properties":{"format":{"type":"string","enum":["TEXT","IMAGE","VIDEO","DOCUMENT","LOCATION"],"description":"TEXT | IMAGE | VIDEO | DOCUMENT | LOCATION."},"text":{"type":"string","maxLength":1000,"description":"TEXT header: ≤ 60 chars, at most one {{1}}."},"example":{"type":"string","maxLength":1000,"description":"TEXT header with {{1}}: its sample value."},"media_handle":{"type":"string","maxLength":4000,"description":"IMAGE/VIDEO/DOCUMENT header: the Meta upload handle used as the sample (`POST /v1/templates/samples`)."}},"required":["format"]},"body":{"default":{},"description":"Body.","type":"object","properties":{"text":{"type":"string","maxLength":5000,"description":"Body text (≤ 1024 chars) with {{1}}, {{2}} … variables. Omit for AUTHENTICATION (Meta fixes it)."},"examples":{"description":"One sample per body variable, in order ({{1}} first).","maxItems":100,"type":"array","items":{"type":"string","maxLength":1000,"description":"Sample value."}},"add_security_recommendation":{"description":"AUTHENTICATION only: append \"For your security, do not share this code.\"","type":"boolean"}}},"footer":{"description":"Optional footer.","type":"object","properties":{"text":{"type":"string","maxLength":1000,"description":"Footer text (≤ 60 chars, no variables)."},"code_expiration_minutes":{"description":"AUTHENTICATION only: code expiry shown in the footer (1-90).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"buttons":{"description":"Buttons in display order (≤ 10).","maxItems":30,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE","FLOW","VOICE_CALL","OTP"],"description":"QUICK_REPLY | URL | PHONE_NUMBER | COPY_CODE | FLOW | VOICE_CALL | OTP."},"text":{"type":"string","maxLength":200,"description":"Button label (≤ 25 chars). Not used for COPY_CODE."},"url":{"type":"string","maxLength":4000,"description":"URL buttons: https URL; for a dynamic URL end it with {{1}} (e.g. https://shop.example/track/{{1}})."},"url_example":{"type":"string","maxLength":4000,"description":"Dynamic URL buttons: a full example URL with the variable filled in."},"phone_number":{"type":"string","maxLength":64,"description":"PHONE_NUMBER buttons: E.164 number, e.g. +971501234567."},"coupon_code":{"type":"string","maxLength":64,"description":"COPY_CODE buttons: the coupon code to copy (≤ 20 chars)."},"flow_id":{"type":"string","maxLength":64,"description":"FLOW buttons: the WhatsApp flow id."},"flow_action":{"description":"FLOW buttons: NAVIGATE (default) or DATA_EXCHANGE for endpoint flows.","type":"string","enum":["NAVIGATE","DATA_EXCHANGE"]},"navigate_screen":{"type":"string","maxLength":200,"description":"FLOW buttons with NAVIGATE: the first screen id."},"otp_type":{"description":"OTP buttons: COPY_CODE (default), ONE_TAP or ZERO_TAP.","type":"string","enum":["COPY_CODE","ONE_TAP","ZERO_TAP"]},"supported_apps":{"description":"ONE_TAP / ZERO_TAP OTP buttons: your Android app(s).","maxItems":5,"type":"array","items":{"type":"object","properties":{"package_name":{"type":"string","maxLength":255,"description":"Android package name."},"signature_hash":{"type":"string","maxLength":64,"description":"App signing key hash."}},"required":["package_name","signature_hash"]}}},"required":["type"],"description":"One button."}},"limited_time_offer":{"description":"Limited-time offer (MARKETING; needs a COPY_CODE button).","type":"object","properties":{"text":{"type":"string","maxLength":200,"description":"Offer text shown on the chip (≤ 16 chars)."},"has_expiration":{"description":"Show a countdown (the expiry is set when sending).","type":"boolean"}},"required":["text"]},"carousel":{"description":"Media carousel (MARKETING): the body is the message above the cards; no top-level header, footer or buttons.","type":"object","properties":{"cards":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"header_format":{"type":"string","enum":["IMAGE","VIDEO"],"description":"Card media type (the same on every card)."},"media_handle":{"type":"string","maxLength":4000,"description":"Meta upload handle for the card media (`POST /v1/templates/samples`)."},"body":{"description":"Card text.","type":"object","properties":{"text":{"type":"string","maxLength":1000,"description":"Card text (≤ 160 chars, {{1}}… allowed)."},"examples":{"description":"One sample per card variable.","maxItems":20,"type":"array","items":{"type":"string","maxLength":1000,"description":"Sample value."}}},"required":["text"]},"buttons":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE","FLOW","VOICE_CALL","OTP"],"description":"QUICK_REPLY | URL | PHONE_NUMBER | COPY_CODE | FLOW | VOICE_CALL | OTP."},"text":{"type":"string","maxLength":200,"description":"Button label (≤ 25 chars). Not used for COPY_CODE."},"url":{"type":"string","maxLength":4000,"description":"URL buttons: https URL; for a dynamic URL end it with {{1}} (e.g. https://shop.example/track/{{1}})."},"url_example":{"type":"string","maxLength":4000,"description":"Dynamic URL buttons: a full example URL with the variable filled in."},"phone_number":{"type":"string","maxLength":64,"description":"PHONE_NUMBER buttons: E.164 number, e.g. +971501234567."},"coupon_code":{"type":"string","maxLength":64,"description":"COPY_CODE buttons: the coupon code to copy (≤ 20 chars)."},"flow_id":{"type":"string","maxLength":64,"description":"FLOW buttons: the WhatsApp flow id."},"flow_action":{"description":"FLOW buttons: NAVIGATE (default) or DATA_EXCHANGE for endpoint flows.","type":"string","enum":["NAVIGATE","DATA_EXCHANGE"]},"navigate_screen":{"type":"string","maxLength":200,"description":"FLOW buttons with NAVIGATE: the first screen id."},"otp_type":{"description":"OTP buttons: COPY_CODE (default), ONE_TAP or ZERO_TAP.","type":"string","enum":["COPY_CODE","ONE_TAP","ZERO_TAP"]},"supported_apps":{"description":"ONE_TAP / ZERO_TAP OTP buttons: your Android app(s).","maxItems":5,"type":"array","items":{"type":"object","properties":{"package_name":{"type":"string","maxLength":255,"description":"Android package name."},"signature_hash":{"type":"string","maxLength":64,"description":"App signing key hash."}},"required":["package_name","signature_hash"]}}},"required":["type"],"description":"One button."},"description":"1-2 buttons (QUICK_REPLY, URL, PHONE_NUMBER), the same layout on every card."}},"required":["header_format","media_handle","buttons"]},"description":"2-10 cards."}},"required":["cards"]}},"required":["name","language","category"],"description":"The new content. `name` and `language` must match the template's."}},"required":["template"],"additionalProperties":false},"examples":{"wording":{"summary":"Change the body wording","value":{"template":{"name":"order_shipped","language":"en_US","category":"UTILITY","body":{"text":"Hi {{1}}, good news: your order {{2}} has shipped.","examples":["Jane","#1001"]}}}}}}}},"responses":{"200":{"description":"Resubmitted for review.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"lint":{"type":"object","properties":{"valid":{"type":"boolean","description":"true when there are no errors (warnings may remain)."},"errors":{"type":"number"},"warnings":{"type":"number"},"issues":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"severity":{"type":"string","enum":["error","warning","info"]},"path":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"}},"required":["rule","severity","path","message","fix"],"additionalProperties":false}},"variables":{"type":"object","properties":{"header":{"type":"number"},"body":{"type":"number"}},"required":["header","body"],"additionalProperties":false},"preview":{"description":"Body with samples filled in.","type":["string","null"]}},"required":["valid","errors","warnings","issues","variables","preview"],"additionalProperties":false},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","name","status","lint"]},"examples":{"wording":{"summary":"Change the body wording","value":{"id":"9120","name":"order_shipped","status":"PENDING","lint":{"valid":true,"errors":0,"warnings":0,"issues":[],"variables":{"header":0,"body":2},"preview":null}}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The draft breaks a template rule (`reason: template_rules`), or its name, language or approved category differs from the template's.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The draft breaks a template rule (`reason: template_rules`), or its name, language or approved category differs from the template's.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The draft breaks a template rule (`reason: template_rules`), or its name, language or approved category differs from the template's.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No template with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No template with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No template with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: The template is under review or otherwise not editable (`reason: not_editable`). Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"The template is under review or otherwise not editable (`reason: not_editable`). Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"The template is under review or otherwise not editable (`reason: not_editable`). Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: submit` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: submit` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: submit` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"502":{"description":"`upstream_error`: WhatsApp refused the edit.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_error":{"summary":"WhatsApp refused the edit.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_error","title":"A connected service answered unexpectedly","status":502,"detail":"WhatsApp refused the edit.","code":"upstream_error","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_update_template","x-platform-ops-path":"/ops/messaging_update_template","x-platform-group":"templates","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":"submit","x-platform-undo":"Edit it again with the old content (it is reviewed again).","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The draft breaks a template rule (`reason: template_rules`), or its name, language or approved category differs from the template's."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No template with this id."},{"code":"conflict","status":409,"when":"The template is under review or otherwise not editable (`reason: not_editable`). Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: submit` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_error","status":502,"when":"WhatsApp refused the edit."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"wording","summary":"Change the body wording","path":{"template_id":"9120"},"query":{},"body":{"template":{"name":"order_shipped","language":"en_US","category":"UTILITY","body":{"text":"Hi {{1}}, good news: your order {{2}} has shipped.","examples":["Jane","#1001"]}}},"response":{"status":200,"body":{"id":"9120","name":"order_shipped","status":"PENDING","lint":{"valid":true,"errors":0,"warnings":0,"issues":[],"variables":{"header":0,"body":2},"preview":null}}}}]}},"/templates/lint":{"post":{"operationId":"lintTemplate","summary":"Check a template draft","description":"Checks a template draft against WhatsApp's rules — names, categories, lengths, variables and buttons — without saving or submitting anything. Every issue comes with a fix.","tags":["templates"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"object","properties":{"name":{"type":"string","maxLength":1000,"description":"Template name: lowercase letters, digits, underscores (e.g. order_shipped_v2)."},"language":{"type":"string","maxLength":20,"description":"Meta language code, e.g. en, en_US, ar, hi, pt_BR."},"category":{"type":"string","maxLength":40,"description":"MARKETING | UTILITY | AUTHENTICATION."},"header":{"description":"Optional header.","type":"object","properties":{"format":{"type":"string","enum":["TEXT","IMAGE","VIDEO","DOCUMENT","LOCATION"],"description":"TEXT | IMAGE | VIDEO | DOCUMENT | LOCATION."},"text":{"type":"string","maxLength":1000,"description":"TEXT header: ≤ 60 chars, at most one {{1}}."},"example":{"type":"string","maxLength":1000,"description":"TEXT header with {{1}}: its sample value."},"media_handle":{"type":"string","maxLength":4000,"description":"IMAGE/VIDEO/DOCUMENT header: the Meta upload handle used as the sample (`POST /v1/templates/samples`)."}},"required":["format"]},"body":{"default":{},"description":"Body.","type":"object","properties":{"text":{"type":"string","maxLength":5000,"description":"Body text (≤ 1024 chars) with {{1}}, {{2}} … variables. Omit for AUTHENTICATION (Meta fixes it)."},"examples":{"description":"One sample per body variable, in order ({{1}} first).","maxItems":100,"type":"array","items":{"type":"string","maxLength":1000,"description":"Sample value."}},"add_security_recommendation":{"description":"AUTHENTICATION only: append \"For your security, do not share this code.\"","type":"boolean"}}},"footer":{"description":"Optional footer.","type":"object","properties":{"text":{"type":"string","maxLength":1000,"description":"Footer text (≤ 60 chars, no variables)."},"code_expiration_minutes":{"description":"AUTHENTICATION only: code expiry shown in the footer (1-90).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"buttons":{"description":"Buttons in display order (≤ 10).","maxItems":30,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE","FLOW","VOICE_CALL","OTP"],"description":"QUICK_REPLY | URL | PHONE_NUMBER | COPY_CODE | FLOW | VOICE_CALL | OTP."},"text":{"type":"string","maxLength":200,"description":"Button label (≤ 25 chars). Not used for COPY_CODE."},"url":{"type":"string","maxLength":4000,"description":"URL buttons: https URL; for a dynamic URL end it with {{1}} (e.g. https://shop.example/track/{{1}})."},"url_example":{"type":"string","maxLength":4000,"description":"Dynamic URL buttons: a full example URL with the variable filled in."},"phone_number":{"type":"string","maxLength":64,"description":"PHONE_NUMBER buttons: E.164 number, e.g. +971501234567."},"coupon_code":{"type":"string","maxLength":64,"description":"COPY_CODE buttons: the coupon code to copy (≤ 20 chars)."},"flow_id":{"type":"string","maxLength":64,"description":"FLOW buttons: the WhatsApp flow id."},"flow_action":{"description":"FLOW buttons: NAVIGATE (default) or DATA_EXCHANGE for endpoint flows.","type":"string","enum":["NAVIGATE","DATA_EXCHANGE"]},"navigate_screen":{"type":"string","maxLength":200,"description":"FLOW buttons with NAVIGATE: the first screen id."},"otp_type":{"description":"OTP buttons: COPY_CODE (default), ONE_TAP or ZERO_TAP.","type":"string","enum":["COPY_CODE","ONE_TAP","ZERO_TAP"]},"supported_apps":{"description":"ONE_TAP / ZERO_TAP OTP buttons: your Android app(s).","maxItems":5,"type":"array","items":{"type":"object","properties":{"package_name":{"type":"string","maxLength":255,"description":"Android package name."},"signature_hash":{"type":"string","maxLength":64,"description":"App signing key hash."}},"required":["package_name","signature_hash"]}}},"required":["type"],"description":"One button."}},"limited_time_offer":{"description":"Limited-time offer (MARKETING; needs a COPY_CODE button).","type":"object","properties":{"text":{"type":"string","maxLength":200,"description":"Offer text shown on the chip (≤ 16 chars)."},"has_expiration":{"description":"Show a countdown (the expiry is set when sending).","type":"boolean"}},"required":["text"]},"carousel":{"description":"Media carousel (MARKETING): the body is the message above the cards; no top-level header, footer or buttons.","type":"object","properties":{"cards":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"header_format":{"type":"string","enum":["IMAGE","VIDEO"],"description":"Card media type (the same on every card)."},"media_handle":{"type":"string","maxLength":4000,"description":"Meta upload handle for the card media (`POST /v1/templates/samples`)."},"body":{"description":"Card text.","type":"object","properties":{"text":{"type":"string","maxLength":1000,"description":"Card text (≤ 160 chars, {{1}}… allowed)."},"examples":{"description":"One sample per card variable.","maxItems":20,"type":"array","items":{"type":"string","maxLength":1000,"description":"Sample value."}}},"required":["text"]},"buttons":{"maxItems":5,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["QUICK_REPLY","URL","PHONE_NUMBER","COPY_CODE","FLOW","VOICE_CALL","OTP"],"description":"QUICK_REPLY | URL | PHONE_NUMBER | COPY_CODE | FLOW | VOICE_CALL | OTP."},"text":{"type":"string","maxLength":200,"description":"Button label (≤ 25 chars). Not used for COPY_CODE."},"url":{"type":"string","maxLength":4000,"description":"URL buttons: https URL; for a dynamic URL end it with {{1}} (e.g. https://shop.example/track/{{1}})."},"url_example":{"type":"string","maxLength":4000,"description":"Dynamic URL buttons: a full example URL with the variable filled in."},"phone_number":{"type":"string","maxLength":64,"description":"PHONE_NUMBER buttons: E.164 number, e.g. +971501234567."},"coupon_code":{"type":"string","maxLength":64,"description":"COPY_CODE buttons: the coupon code to copy (≤ 20 chars)."},"flow_id":{"type":"string","maxLength":64,"description":"FLOW buttons: the WhatsApp flow id."},"flow_action":{"description":"FLOW buttons: NAVIGATE (default) or DATA_EXCHANGE for endpoint flows.","type":"string","enum":["NAVIGATE","DATA_EXCHANGE"]},"navigate_screen":{"type":"string","maxLength":200,"description":"FLOW buttons with NAVIGATE: the first screen id."},"otp_type":{"description":"OTP buttons: COPY_CODE (default), ONE_TAP or ZERO_TAP.","type":"string","enum":["COPY_CODE","ONE_TAP","ZERO_TAP"]},"supported_apps":{"description":"ONE_TAP / ZERO_TAP OTP buttons: your Android app(s).","maxItems":5,"type":"array","items":{"type":"object","properties":{"package_name":{"type":"string","maxLength":255,"description":"Android package name."},"signature_hash":{"type":"string","maxLength":64,"description":"App signing key hash."}},"required":["package_name","signature_hash"]}}},"required":["type"],"description":"One button."},"description":"1-2 buttons (QUICK_REPLY, URL, PHONE_NUMBER), the same layout on every card."}},"required":["header_format","media_handle","buttons"]},"description":"2-10 cards."}},"required":["cards"]}},"required":["name","language","category"],"description":"A template draft."}},"required":["template"],"additionalProperties":false},"examples":{"missing-sample":{"summary":"A draft with a missing sample","value":{"template":{"name":"order_shipped","language":"en_US","category":"UTILITY","body":{"text":"Hi {{1}}, your order {{2}} is on its way.","examples":["Jane"]}}}}}}}},"responses":{"200":{"description":"The result of the check.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"valid":{"type":"boolean","description":"true when there are no errors (warnings may remain)."},"errors":{"type":"number"},"warnings":{"type":"number"},"issues":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"severity":{"type":"string","enum":["error","warning","info"]},"path":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"}},"required":["rule","severity","path","message","fix"],"additionalProperties":false}},"variables":{"type":"object","properties":{"header":{"type":"number"},"body":{"type":"number"}},"required":["header","body"],"additionalProperties":false},"preview":{"description":"Body with samples filled in.","type":["string","null"]}},"required":["valid","errors","warnings","issues","variables","preview"]},"examples":{"missing-sample":{"summary":"A draft with a missing sample","value":{"valid":false,"errors":1,"warnings":0,"issues":[{"rule":"body.samples","severity":"error","path":"body.examples","message":"The body has 2 variables but 1 sample.","fix":"Add a sample for {{2}}, e.g. \"#1001\"."}],"variables":{"header":0,"body":2},"preview":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_lint_template","x-platform-ops-path":"/ops/messaging_lint_template","x-platform-group":"templates","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: nothing is saved.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"missing-sample","summary":"A draft with a missing sample","path":{},"query":{},"body":{"template":{"name":"order_shipped","language":"en_US","category":"UTILITY","body":{"text":"Hi {{1}}, your order {{2}} is on its way.","examples":["Jane"]}}},"response":{"status":200,"body":{"valid":false,"errors":1,"warnings":0,"issues":[{"rule":"body.samples","severity":"error","path":"body.examples","message":"The body has 2 variables but 1 sample.","fix":"Add a sample for {{2}}, e.g. \"#1001\"."}],"variables":{"header":0,"body":2},"preview":null}}}]}},"/templates/archive":{"post":{"operationId":"archiveTemplates","summary":"Archive templates","description":"Archives up to 20 templates. **They can no longer be sent**: chatbots, automations and broadcasts that use them start failing. An archived template can be restored in the app for 28 days.\n\nThe answer lists what was archived and what failed, each failure with a stable `code` and a sentence. Needs `Api-Confirm: archive`.","tags":["templates"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":20,"type":"array","items":{"description":"Template id.","anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"description":"Template ids (1–20).","x-platform-picker":"templates"}},"required":["ids"],"additionalProperties":false},"examples":{"old":{"summary":"Archive two old templates","value":{"ids":["9120","9121"]}}}}}},"responses":{"200":{"description":"Archived ids, and the ones that failed: a stable `code` (`not_found`, `account_not_connected`, `not_submitted`, `refused_by_whatsapp`) and a sentence for it.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"archived":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"code":{"type":"string","enum":["not_found","account_not_connected","not_submitted","refused_by_whatsapp"]},"reason":{"type":"string","description":"A fixed sentence for the code."}},"required":["id","name","code","reason"],"additionalProperties":false}},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["archived","failed"]},"examples":{"old":{"summary":"Archive two old templates","value":{"archived":["9120"],"failed":[{"id":"9121","name":"summer_sale","code":"refused_by_whatsapp","reason":"WhatsApp refused to archive this template. Try again later, or archive it in the app."}]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: archive` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: archive` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: archive` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_archive_templates","x-platform-ops-path":"/ops/messaging_archive_templates","x-platform-group":"templates","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":"archive","x-platform-undo":"Restore them in the app within 28 days.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: archive` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"old","summary":"Archive two old templates","path":{},"query":{},"body":{"ids":["9120","9121"]},"response":{"status":200,"body":{"archived":["9120"],"failed":[{"id":"9121","name":"summer_sale","code":"refused_by_whatsapp","reason":"WhatsApp refused to archive this template. Try again later, or archive it in the app."}]}}}]}},"/templates/samples":{"post":{"operationId":"uploadTemplateSample","summary":"Upload a template header sample","description":"WhatsApp reviews an IMAGE, VIDEO or DOCUMENT header by a sample file. Give the public https URL of one file (JPEG or PNG up to 5 MB, MP4 up to 16 MB, or PDF); it is downloaded, checked and uploaded to WhatsApp, and you get a `handle` to put in the draft's `header.media_handle` for **Create a WhatsApp template**.\n\nThe URL must be the file itself (no web page, no redirects) on a public address. Nothing is sent to customers. With `?dry_run=true` (and with a test key) the file is not downloaded: only the URL (public https) and the file type its name declares are checked, and nothing is uploaded. The file's real type and size are checked when it is uploaded.","tags":["templates"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":12,"maxLength":2000,"description":"Public https URL of the file."},"business_account_id":{"description":"The WhatsApp account the template will belong to. Needed only when your workspace has several.","type":"string","maxLength":64},"channel_id":{"description":"Instead of `business_account_id`: a connected WhatsApp channel; its account is used.","type":"string","maxLength":64,"x-platform-picker":"channels"}},"required":["url"],"additionalProperties":false},"examples":{"banner":{"summary":"An image header sample","value":{"url":"https://cdn.example.com/banner.png"}}}}}},"responses":{"200":{"description":"The handle, and the header format the file fits.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"handle":{"type":"string","description":"Put this in the draft's header.mediaHandle (valid for the template submission)."},"header_format":{"type":"string","enum":["IMAGE","VIDEO","DOCUMENT"],"description":"The header format this file fits."},"mime_type":{"type":"string"},"bytes":{"type":"number"},"business_account_id":{"type":"string"},"business_account_name":{"type":"string"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["handle","header_format","mime_type","bytes","business_account_id","business_account_name"]},"examples":{"banner":{"summary":"An image header sample","value":{"handle":"4::aW1hZ2UvcG5n:ARbExample","header_format":"IMAGE","mime_type":"image/png","bytes":48213,"business_account_id":"4410","business_account_name":"Main WhatsApp"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The URL is not a public https file, the type or size is not allowed, or the workspace has several WhatsApp accounts and none was chosen.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The URL is not a public https file, the type or size is not allowed, or the workspace has several WhatsApp accounts and none was chosen.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The URL is not a public https file, the type or size is not allowed, or the workspace has several WhatsApp accounts and none was chosen.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"502":{"description":"`upstream_error`: WhatsApp did not accept the file.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_error":{"summary":"WhatsApp did not accept the file.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_error","title":"A connected service answered unexpectedly","status":502,"detail":"WhatsApp did not accept the file.","code":"upstream_error","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_upload_template_sample","x-platform-ops-path":"/ops/messaging_upload_template_sample","x-platform-group":"templates","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: an unused sample expires on its own.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The URL is not a public https file, the type or size is not allowed, or the workspace has several WhatsApp accounts and none was chosen."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_error","status":502,"when":"WhatsApp did not accept the file."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"banner","summary":"An image header sample","path":{},"query":{},"body":{"url":"https://cdn.example.com/banner.png"},"response":{"status":200,"body":{"handle":"4::aW1hZ2UvcG5n:ARbExample","header_format":"IMAGE","mime_type":"image/png","bytes":48213,"business_account_id":"4410","business_account_name":"Main WhatsApp"}}}]}},"/broadcasts":{"get":{"operationId":"listBroadcasts","summary":"List broadcasts","description":"Lists your WhatsApp broadcasts, newest first, with their status, channel, template, audience size and delivery numbers. Broadcasts are created and sent by your team in the app; the API reads them.","tags":["broadcasts"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"search","in":"query","required":false,"description":"Name contains this text.","schema":{"description":"Name contains this text.","type":"string","maxLength":100}},{"name":"statuses","in":"query","required":false,"description":"Only these statuses (repeat the parameter).","schema":{"description":"Only these statuses (repeat the parameter).","maxItems":12,"type":"array","items":{"type":"string","enum":["SCHEDULED","PENDING","ADDING_CONTACTS","ADDING_CONTACTS_DONE","SENDING_MESSAGE_TO_CONTACTS","COMPLETE","ERROR","CANCELLED","STOPPED","PAUSED","RUNNING","PARTIALLY_SENT"]}},"style":"form","explode":true},{"name":"campaign_id","in":"query","required":false,"description":"Only broadcasts of this campaign.","schema":{"description":"Only broadcasts of this campaign.","type":"string","maxLength":20}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of broadcasts.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"status":{"type":["string","null"]},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"template":{"anyOf":[{"type":"object","properties":{"name":{"type":["string","null"]},"language":{"type":["string","null"]},"category":{"type":["string","null"]}},"required":["name","language","category"],"additionalProperties":false},{"type":"null"}]},"audience_size":{"description":"Estimated recipients when set up; stats.total once sending started.","type":["number","null"]},"scheduled_at":{"type":["string","null"]},"created_at":{"type":["string","null"]},"sandbox":{"type":"boolean"},"stats":{"anyOf":[{"type":"object","properties":{"total":{"type":"number"},"pending":{"type":"number"},"sent":{"type":"number"},"delivered":{"type":"number"},"read":{"type":"number"},"failed":{"type":"number"},"dnd":{"type":"number","description":"Skipped because the contact opted out / is on do-not-disturb."},"responded":{"type":"number"},"converted":{"type":"number"},"delivery_rate":{"description":"delivered / sent, 0-1.","type":["number","null"]},"read_rate":{"description":"read / delivered, 0-1.","type":["number","null"]}},"required":["total","pending","sent","delivered","read","failed","dnd","responded","converted","delivery_rate","read_rate"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","status","channel","template","audience_size","scheduled_at","created_at","sandbox","stats"],"additionalProperties":false}},"total":{"type":"number"},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","next_cursor"]},"examples":{"done":{"summary":"Completed broadcasts","value":{"data":[{"id":"301","name":"September sale","status":"COMPLETE","channel":{"id":"7","name":"Main WhatsApp"},"template":{"name":"summer_sale","language":"en","category":"MARKETING"},"audience_size":1000,"scheduled_at":null,"created_at":"2026-09-10T08:00:00Z","sandbox":false,"stats":{"total":1000,"pending":0,"sent":980,"delivered":950,"read":600,"failed":20,"dnd":5,"responded":40,"converted":10,"delivery_rate":0.969,"read_rate":0.632}}],"next_cursor":null,"total":1}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_list_broadcasts","x-platform-ops-path":"/ops/messaging_list_broadcasts","x-platform-group":"broadcasts","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"done","summary":"Completed broadcasts","path":{},"query":{"statuses":["COMPLETE"]},"response":{"status":200,"body":{"data":[{"id":"301","name":"September sale","status":"COMPLETE","channel":{"id":"7","name":"Main WhatsApp"},"template":{"name":"summer_sale","language":"en","category":"MARKETING"},"audience_size":1000,"scheduled_at":null,"created_at":"2026-09-10T08:00:00Z","sandbox":false,"stats":{"total":1000,"pending":0,"sent":980,"delivered":950,"read":600,"failed":20,"dnd":5,"responded":40,"converted":10,"delivery_rate":0.969,"read_rate":0.632}}],"next_cursor":null,"total":1}}}]}},"/broadcasts/{broadcast_id}":{"get":{"operationId":"getBroadcast","summary":"Get a broadcast","description":"Returns one broadcast: status, channel, template, audience (contact groups and size), schedule, send rate and delivery numbers (sent, delivered, read, failed, opted out, responded, and the rates).","tags":["broadcasts"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"broadcast_id","in":"path","required":true,"description":"The broadcast id.","schema":{"description":"Broadcast id.","anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The broadcast.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"status":{"type":["string","null"]},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"template":{"anyOf":[{"type":"object","properties":{"name":{"type":["string","null"]},"language":{"type":["string","null"]},"category":{"type":["string","null"]}},"required":["name","language","category"],"additionalProperties":false},{"type":"null"}]},"audience_size":{"description":"Estimated recipients when set up; stats.total once sending started.","type":["number","null"]},"scheduled_at":{"type":["string","null"]},"created_at":{"type":["string","null"]},"sandbox":{"type":"boolean"},"stats":{"anyOf":[{"type":"object","properties":{"total":{"type":"number"},"pending":{"type":"number"},"sent":{"type":"number"},"delivered":{"type":"number"},"read":{"type":"number"},"failed":{"type":"number"},"dnd":{"type":"number","description":"Skipped because the contact opted out / is on do-not-disturb."},"responded":{"type":"number"},"converted":{"type":"number"},"delivery_rate":{"description":"delivered / sent, 0-1.","type":["number","null"]},"read_rate":{"description":"read / delivered, 0-1.","type":["number","null"]}},"required":["total","pending","sent","delivered","read","failed","dnd","responded","converted","delivery_rate","read_rate"],"additionalProperties":false},{"type":"null"}]},"contact_groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false}},"timezone":{"type":["string","null"]},"message_rate":{"description":"e.g. \"100 per minute\".","type":["string","null"]},"stopped_at":{"type":["string","null"]},"paused_at":{"type":["string","null"]},"cancelled_at":{"type":["string","null"]}},"required":["id","name","status","channel","template","audience_size","scheduled_at","created_at","sandbox","stats","contact_groups","timezone","message_rate","stopped_at","paused_at","cancelled_at"]},"examples":{"one":{"summary":"Read one broadcast","value":{"id":"301","name":"September sale","status":"COMPLETE","channel":{"id":"7","name":"Main WhatsApp"},"template":{"name":"summer_sale","language":"en","category":"MARKETING"},"audience_size":1000,"scheduled_at":null,"created_at":"2026-09-10T08:00:00Z","sandbox":false,"stats":{"total":1000,"pending":0,"sent":980,"delivered":950,"read":600,"failed":20,"dnd":5,"responded":40,"converted":10,"delivery_rate":0.969,"read_rate":0.632},"contact_groups":[{"id":"5","name":"Newsletter"}],"timezone":"Asia/Dubai","message_rate":"100 per minute","stopped_at":null,"paused_at":null,"cancelled_at":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No broadcast with this id in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No broadcast with this id in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No broadcast with this id in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_get_broadcast","x-platform-ops-path":"/ops/messaging_get_broadcast","x-platform-group":"broadcasts","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No broadcast with this id in your workspace."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"one","summary":"Read one broadcast","path":{"broadcast_id":"301"},"query":{},"response":{"status":200,"body":{"id":"301","name":"September sale","status":"COMPLETE","channel":{"id":"7","name":"Main WhatsApp"},"template":{"name":"summer_sale","language":"en","category":"MARKETING"},"audience_size":1000,"scheduled_at":null,"created_at":"2026-09-10T08:00:00Z","sandbox":false,"stats":{"total":1000,"pending":0,"sent":980,"delivered":950,"read":600,"failed":20,"dnd":5,"responded":40,"converted":10,"delivery_rate":0.969,"read_rate":0.632},"contact_groups":[{"id":"5","name":"Newsletter"}],"timezone":"Asia/Dubai","message_rate":"100 per minute","stopped_at":null,"paused_at":null,"cancelled_at":null}}}]}},"/broadcasts/precheck":{"post":{"operationId":"precheckBroadcast","summary":"Check broadcast readiness","description":"Runs the workspace's broadcast readiness check (channel connected, messaging limits, plan and quota, billing) and lists each check as `PASS`, `WARNING` or `FAIL`, with whether it blocks sending. **It sends nothing and changes nothing**; it is a POST because the check runs live.\n\nWith a test key or `?dry_run=true` the check does not run: you get the example answer.","tags":["broadcasts"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"Each check (`channel_connected`, `service_health`, `usage_limits`, `phone_quality`, `payment_method`, `system_error`, `other`) with its status and a sentence, and whether you can send. `errors` repeats the sentence of each failed blocking check, `warnings` that of each warning.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"can_send":{"type":"boolean"},"checks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["channel_connected","service_health","usage_limits","phone_quality","payment_method","system_error","other"],"description":"Stable check name."},"status":{"type":"string"},"message":{"type":"string","description":"A fixed sentence for the check and its status."},"blocking":{"type":"boolean"}},"required":["name","status","message","blocking"],"additionalProperties":false}},"errors":{"type":"array","items":{"type":"string"},"description":"The sentence of each failed blocking check."},"warnings":{"type":"array","items":{"type":"string"},"description":"The sentence of each check with a warning."},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["can_send","checks","errors","warnings"]},"examples":{"ready":{"summary":"Ready to send","value":{"can_send":true,"checks":[{"name":"channel_connected","status":"PASS","message":"Your WhatsApp channel is connected.","blocking":true},{"name":"phone_quality","status":"WARNING","message":"Your WhatsApp number's quality rating is low; WhatsApp may limit how many customers you can message.","blocking":false}],"errors":[],"warnings":["Your WhatsApp number's quality rating is low; WhatsApp may limit how many customers you can message."]}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_precheck_broadcast","x-platform-ops-path":"/ops/messaging_precheck_broadcast","x-platform-group":"broadcasts","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"none","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: nothing changes.","x-platform-events":[],"x-platform-errors":[{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"ready","summary":"Ready to send","path":{},"query":{},"response":{"status":200,"body":{"can_send":true,"checks":[{"name":"channel_connected","status":"PASS","message":"Your WhatsApp channel is connected.","blocking":true},{"name":"phone_quality","status":"WARNING","message":"Your WhatsApp number's quality rating is low; WhatsApp may limit how many customers you can message.","blocking":false}],"errors":[],"warnings":["Your WhatsApp number's quality rating is low; WhatsApp may limit how many customers you can message."]}}}]}},"/messages/template":{"post":{"operationId":"sendTemplateMessage","summary":"Send a WhatsApp template","description":"Sends one approved WhatsApp template to one contact, now. **The customer receives it and it cannot be undone.**\n\nThe variables are checked against the template first. Opt-outs and do-not-disturb are always respected. For bulk sends, use a broadcast in the app instead.\n\nTry it with `?dry_run=true`: every check runs and the preview tells you which number it would send from, but nothing is sent.","tags":["messages"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"description":"Who receives it.","anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}],"x-platform-picker":"contacts"},"template_id":{"description":"An APPROVED template.","anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}],"x-platform-picker":"templates"},"channel_id":{"description":"Send from this WhatsApp channel. Default: your default WhatsApp channel.","type":"string","maxLength":20,"x-platform-picker":"channels"},"body_variables":{"default":[],"description":"One value per `{{n}}` in the body, in order. No new lines or tabs.","maxItems":100,"type":"array","items":{"type":"string","maxLength":1024,"description":"Value."}},"header_text":{"description":"Value for a `{{1}}` in a TEXT header.","type":"string","maxLength":60},"header_media_url":{"description":"https link to the image, video or document for a media header.","type":"string","maxLength":2000,"format":"uri"},"button_url_suffixes":{"default":[],"description":"One per dynamic URL button.","maxItems":2,"type":"array","items":{"type":"object","properties":{"button_index":{"type":"integer","minimum":0,"maximum":9,"description":"Button position (0-based, from `GET /v1/templates/{template_id}`)."},"value":{"type":"string","maxLength":2000,"description":"Suffix replacing {{1}} in the URL."}},"required":["button_index","value"]}}},"required":["contact_id","template_id"],"additionalProperties":false},"examples":{"shipped":{"summary":"Tell a customer their order shipped","value":{"contact_id":"48213","template_id":"9120","channel_id":"301","body_variables":["Jane","#1001","https://track.example.com/1001"]}}}}}},"responses":{"202":{"description":"Accepted for delivery (or the dry-run preview).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"message_id":{"type":["string","null"]},"conversation_id":{"type":["string","null"]},"status":{"type":"string","description":"queued (accepted for delivery) or failed."},"template":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":["string","null"]}},"required":["id","name","language"],"additionalProperties":false},"sent_at":{"type":["string","null"]},"would_send_from":{"description":"Dry run only: the channel it would send from.","anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"identifier":{"type":["string","null"]}},"required":["id","name","identifier"],"additionalProperties":false},{"type":"null"}]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["message_id","conversation_id","status","template","sent_at"]},"examples":{"shipped":{"summary":"Tell a customer their order shipped","value":{"message_id":null,"conversation_id":"77410","status":"dry_run","template":{"id":"9120","name":"order_shipped","language":"en_US"},"sent_at":null,"would_send_from":{"id":"301","name":"Main WhatsApp","identifier":"+15555550100"},"dry_run":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: AUTHENTICATION templates cannot be sent through the API. `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"AUTHENTICATION templates cannot be sent through the API.","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"AUTHENTICATION templates cannot be sent through the API.","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: The contact, template or channel does not exist.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"The contact, template or channel does not exist.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"The contact, template or channel does not exist.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: The template is not APPROVED, or the channel is not connected. Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"The template is not APPROVED, or the channel is not connected. Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"The template is not APPROVED, or the channel is not connected. Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day).","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day).","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_send_template_message","x-platform-ops-path":"/ops/messaging_send_template_message","x-platform-group":"messages","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-send-caps":{"per_hour":20,"per_day":100,"per_recipient_per_day":3},"x-platform-idempotency":"required","x-platform-dry-run":"native","x-platform-destructive-verb":null,"x-platform-undo":"Cannot be undone: the customer receives the message.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"AUTHENTICATION templates cannot be sent through the API."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"The contact, template or channel does not exist."},{"code":"conflict","status":409,"when":"The template is not APPROVED, or the channel is not connected. Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day)."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"shipped","summary":"Tell a customer their order shipped","path":{},"query":{"dry_run":true},"body":{"contact_id":"48213","template_id":"9120","channel_id":"301","body_variables":["Jane","#1001","https://track.example.com/1001"]},"response":{"status":202,"body":{"message_id":null,"conversation_id":"77410","status":"dry_run","template":{"id":"9120","name":"order_shipped","language":"en_US"},"sent_at":null,"would_send_from":{"id":"301","name":"Main WhatsApp","identifier":"+15555550100"},"dry_run":true}}}]}},"/short-links":{"get":{"operationId":"listShortLinks","summary":"List WhatsApp short links","description":"Lists your WhatsApp click-to-chat short links, newest first. Each one is a `https://wa.me/message/…` link that opens a chat with one of your WhatsApp numbers with a message already typed, and usually a QR code image of it. Each link names the number it belongs to.","tags":["short-links"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"channel_id","in":"query","required":false,"description":"Only links of this WhatsApp channel.","schema":{"description":"Only links of this WhatsApp channel.","type":"string","maxLength":64},"x-platform-picker":"channels"},{"name":"phone","in":"query","required":false,"description":"Only links of this WhatsApp number, in any format (`+1 555-555-0100`).","schema":{"description":"Only links of this WhatsApp number, in any format (`+1 555-555-0100`).","type":"string","maxLength":32}},{"name":"search","in":"query","required":false,"description":"The message contains this text (case-insensitive).","schema":{"description":"The message contains this text (case-insensitive).","type":"string","maxLength":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of short links.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","description":"The code at the end of the link."},"url":{"type":"string","description":"The click-to-chat link (https://wa.me/message/…). Share it, or print its QR code."},"message":{"description":"The text the customer finds already typed; they can edit it before sending.","type":["string","null"]},"qr_image_url":{"description":"QR code image of the link, hosted by WhatsApp. The link can expire: download and keep your own copy for print.","type":["string","null"]},"qr_image_format":{"anyOf":[{"type":"string","enum":["PNG","SVG"]},{"type":"null"}],"description":"PNG or SVG; null when there is no image or its format is not known."},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Workspace channel id (as `GET /v1/channels` lists it)."},"name":{"type":["string","null"]},"phone":{"description":"The WhatsApp number the link opens a chat with.","type":["string","null"]}},"required":["id","name","phone"],"additionalProperties":false},{"type":"null"}],"description":"The WhatsApp number it belongs to."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","code","url","message","qr_image_url","qr_image_format","channel","created_at","updated_at"],"additionalProperties":false}},"total":{"type":"number"},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","next_cursor"]},"examples":{"all":{"summary":"All short links","value":{"data":[{"id":"sl-12","code":"4PZQX7M2LCKHA1","url":"https://wa.me/message/4PZQX7M2LCKHA1","message":"Hi! I'd like to order 🍕","qr_image_url":"https://scontent-bom5-2.xx.fbcdn.net/m1/v/t6/An9_qr4PZQX7M2LCKHA1?ccb=10-5&oe=66F00000","qr_image_format":"PNG","channel":{"id":"301","name":"Main WhatsApp","phone":"+1 555-555-0100"},"created_at":"2026-09-12T10:00:00.000Z","updated_at":"2026-09-12T10:00:00.000Z"}],"next_cursor":null,"total":1}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: The channel, or a connected number with this phone, is not in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"The channel, or a connected number with this phone, is not in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"The channel, or a connected number with this phone, is not in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_list_short_links","x-platform-ops-path":"/ops/messaging_list_short_links","x-platform-group":"short-links","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"The channel, or a connected number with this phone, is not in your workspace."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"all","summary":"All short links","path":{},"query":{},"response":{"status":200,"body":{"data":[{"id":"sl-12","code":"4PZQX7M2LCKHA1","url":"https://wa.me/message/4PZQX7M2LCKHA1","message":"Hi! I'd like to order 🍕","qr_image_url":"https://scontent-bom5-2.xx.fbcdn.net/m1/v/t6/An9_qr4PZQX7M2LCKHA1?ccb=10-5&oe=66F00000","qr_image_format":"PNG","channel":{"id":"301","name":"Main WhatsApp","phone":"+1 555-555-0100"},"created_at":"2026-09-12T10:00:00.000Z","updated_at":"2026-09-12T10:00:00.000Z"}],"next_cursor":null,"total":1}}}]},"post":{"operationId":"createShortLink","summary":"Create a short link","description":"Creates a WhatsApp click-to-chat short link: a `https://wa.me/message/…` link that opens a chat with one of your connected WhatsApp numbers with `message` already typed (the customer can edit it before sending). A QR code image of the link comes with it, PNG unless you ask for `SVG` or `NONE`.\n\n- `message`: 1–140 characters of plain text (an emoji counts as 2). New lines, emoji and links are fine; do not URL-encode it.\n- The number: `channel_id` or `phone`. Needed only when several numbers are connected (`400`, `reason: channel_ambiguous`, with the choices).\n- A second link with the same message on the same number is refused with `409` (`reason: duplicate`, `existing_id`) unless `allow_duplicate` is `true`.\n\nThe QR image is hosted by WhatsApp and its URL can expire: download it and keep your own copy for print. Run it with `?dry_run=true` (a test key always does): every check runs and the answer names the number, but nothing is created.","tags":["short-links"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","maxLength":1000,"description":"The text the customer finds typed: 1–140 characters, plain text (an emoji counts as 2)."},"channel_id":{"description":"The WhatsApp channel the link opens a chat with. Needed only when several numbers are connected.","type":"string","maxLength":64,"x-platform-picker":"channels"},"phone":{"description":"Instead of `channel_id`: the connected WhatsApp number, in any format.","type":"string","maxLength":32},"qr_format":{"default":"PNG","description":"`PNG` (default), `SVG`, or `NONE` for no QR image.","type":"string","enum":["PNG","SVG","NONE"]},"allow_duplicate":{"description":"`true` = create even when the number already has a link with this exact message.","type":"boolean"}},"required":["message"],"additionalProperties":false},"examples":{"order":{"summary":"A link that starts an order","value":{"message":"Hi! I'd like to order 🍕","channel_id":"301"}}}}}},"responses":{"201":{"description":"The new short link (a dry run: `id`, `code` and `url` are null, `dry_run` is true).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":["string","null"]},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"message":{"description":"The text the customer finds already typed; they can edit it before sending.","type":["string","null"]},"qr_image_url":{"description":"QR code image of the link, hosted by WhatsApp. The link can expire: download and keep your own copy for print.","type":["string","null"]},"qr_image_format":{"anyOf":[{"type":"string","enum":["PNG","SVG"]},{"type":"null"}],"description":"PNG or SVG; null when there is no image or its format is not known."},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Workspace channel id (as `GET /v1/channels` lists it)."},"name":{"type":["string","null"]},"phone":{"description":"The WhatsApp number the link opens a chat with.","type":["string","null"]}},"required":["id","name","phone"],"additionalProperties":false},{"type":"null"}],"description":"The WhatsApp number it belongs to."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","code","url","message","qr_image_url","qr_image_format","channel","created_at","updated_at"]},"examples":{"order":{"summary":"A link that starts an order","value":{"id":"sl-12","code":"4PZQX7M2LCKHA1","url":"https://wa.me/message/4PZQX7M2LCKHA1","message":"Hi! I'd like to order 🍕","qr_image_url":"https://scontent-bom5-2.xx.fbcdn.net/m1/v/t6/An9_qr4PZQX7M2LCKHA1?ccb=10-5&oe=66F00000","qr_image_format":"PNG","channel":{"id":"301","name":"Main WhatsApp","phone":"+1 555-555-0100"},"created_at":"2026-09-12T10:00:00.000Z","updated_at":"2026-09-12T10:00:00.000Z"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The message breaks a rule (`reason`: `message_empty`, `message_too_long`, `message_control_chars`, `message_url_encoded`), or several numbers are connected and none was chosen (`reason: channel_ambiguous`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The message breaks a rule (`reason`: `message_empty`, `message_too_long`, `message_control_chars`, `message_url_encoded`), or several numbers are connected and none was chosen (`reason: channel_ambiguous`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The message breaks a rule (`reason`: `message_empty`, `message_too_long`, `message_control_chars`, `message_url_encoded`), or several numbers are connected and none was chosen (`reason: channel_ambiguous`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: The channel or phone is not a WhatsApp number of your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"The channel or phone is not a WhatsApp number of your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"The channel or phone is not a WhatsApp number of your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: The number is not connected (`reason: channel_not_connected`), or it already has a link with this message (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"The number is not connected (`reason: channel_not_connected`), or it already has a link with this message (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"The number is not connected (`reason: channel_not_connected`), or it already has a link with this message (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds. WhatsApp is rate limiting short-link changes. Retry after `Retry-After`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. WhatsApp is rate limiting short-link changes. Retry after `Retry-After`.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. WhatsApp is rate limiting short-link changes. Retry after `Retry-After`.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"502":{"description":"`upstream_error`: WhatsApp refused the link (`reason: refused_by_whatsapp`).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_error":{"summary":"WhatsApp refused the link (`reason: refused_by_whatsapp`).","value":{"type":"https://dev.wa-api.cloud/errors/upstream_error","title":"A connected service answered unexpectedly","status":502,"detail":"WhatsApp refused the link (`reason: refused_by_whatsapp`).","code":"upstream_error","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_create_short_link","x-platform-ops-path":"/ops/messaging_create_short_link","x-platform-group":"short-links","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"required","x-platform-dry-run":"native","x-platform-destructive-verb":null,"x-platform-undo":"Delete it with **Delete a short link**.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The message breaks a rule (`reason`: `message_empty`, `message_too_long`, `message_control_chars`, `message_url_encoded`), or several numbers are connected and none was chosen (`reason: channel_ambiguous`). Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"The channel or phone is not a WhatsApp number of your workspace."},{"code":"conflict","status":409,"when":"The number is not connected (`reason: channel_not_connected`), or it already has a link with this message (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. WhatsApp is rate limiting short-link changes. Retry after `Retry-After`."},{"code":"upstream_error","status":502,"when":"WhatsApp refused the link (`reason: refused_by_whatsapp`)."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"order","summary":"A link that starts an order","path":{},"query":{},"body":{"message":"Hi! I'd like to order 🍕","channel_id":"301"},"response":{"status":201,"body":{"id":"sl-12","code":"4PZQX7M2LCKHA1","url":"https://wa.me/message/4PZQX7M2LCKHA1","message":"Hi! I'd like to order 🍕","qr_image_url":"https://scontent-bom5-2.xx.fbcdn.net/m1/v/t6/An9_qr4PZQX7M2LCKHA1?ccb=10-5&oe=66F00000","qr_image_format":"PNG","channel":{"id":"301","name":"Main WhatsApp","phone":"+1 555-555-0100"},"created_at":"2026-09-12T10:00:00.000Z","updated_at":"2026-09-12T10:00:00.000Z"}}}]}},"/short-links/{short_link_id}":{"get":{"operationId":"getShortLink","summary":"Get a short link","description":"Returns one WhatsApp short link: the `wa.me` link, the message it types for the customer, the QR code image and the number it opens a chat with.\n\nThe QR image is hosted by WhatsApp and its URL can expire: download the image and keep your own copy for anything you print.","tags":["short-links"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"short_link_id","in":"path","required":true,"description":"The short link id.","schema":{"description":"Short link id from `GET /v1/short-links`.","anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The short link.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"code":{"type":"string","description":"The code at the end of the link."},"url":{"type":"string","description":"The click-to-chat link (https://wa.me/message/…). Share it, or print its QR code."},"message":{"description":"The text the customer finds already typed; they can edit it before sending.","type":["string","null"]},"qr_image_url":{"description":"QR code image of the link, hosted by WhatsApp. The link can expire: download and keep your own copy for print.","type":["string","null"]},"qr_image_format":{"anyOf":[{"type":"string","enum":["PNG","SVG"]},{"type":"null"}],"description":"PNG or SVG; null when there is no image or its format is not known."},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Workspace channel id (as `GET /v1/channels` lists it)."},"name":{"type":["string","null"]},"phone":{"description":"The WhatsApp number the link opens a chat with.","type":["string","null"]}},"required":["id","name","phone"],"additionalProperties":false},{"type":"null"}],"description":"The WhatsApp number it belongs to."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","code","url","message","qr_image_url","qr_image_format","channel","created_at","updated_at"]},"examples":{"one":{"summary":"Read one short link","value":{"id":"sl-12","code":"4PZQX7M2LCKHA1","url":"https://wa.me/message/4PZQX7M2LCKHA1","message":"Hi! I'd like to order 🍕","qr_image_url":"https://scontent-bom5-2.xx.fbcdn.net/m1/v/t6/An9_qr4PZQX7M2LCKHA1?ccb=10-5&oe=66F00000","qr_image_format":"PNG","channel":{"id":"301","name":"Main WhatsApp","phone":"+1 555-555-0100"},"created_at":"2026-09-12T10:00:00.000Z","updated_at":"2026-09-12T10:00:00.000Z"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No short link with this id in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No short link with this id in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No short link with this id in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_get_short_link","x-platform-ops-path":"/ops/messaging_get_short_link","x-platform-group":"short-links","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No short link with this id in your workspace."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"one","summary":"Read one short link","path":{"short_link_id":"sl-12"},"query":{},"response":{"status":200,"body":{"id":"sl-12","code":"4PZQX7M2LCKHA1","url":"https://wa.me/message/4PZQX7M2LCKHA1","message":"Hi! I'd like to order 🍕","qr_image_url":"https://scontent-bom5-2.xx.fbcdn.net/m1/v/t6/An9_qr4PZQX7M2LCKHA1?ccb=10-5&oe=66F00000","qr_image_format":"PNG","channel":{"id":"301","name":"Main WhatsApp","phone":"+1 555-555-0100"},"created_at":"2026-09-12T10:00:00.000Z","updated_at":"2026-09-12T10:00:00.000Z"}}}]},"patch":{"operationId":"updateShortLink","summary":"Change a short link's message","description":"Changes the message a short link types for the customer. The link and its code stay the same, so links you shared and QR codes you printed keep working and now open the chat with the new message.\n\nThe QR image is generated again, as PNG, at a new URL. The number cannot change: create a new link instead.","tags":["short-links"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"name":"short_link_id","in":"path","required":true,"description":"The short link id.","schema":{"description":"Short link id.","anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","maxLength":1000,"description":"The new text: 1–140 characters, plain text (an emoji counts as 2)."}},"required":["message"],"additionalProperties":false},"examples":{"reword":{"summary":"Change the message","value":{"message":"Hi! I'd like to book a table"}}}}}},"responses":{"200":{"description":"The short link with its new message.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"code":{"type":"string","description":"The code at the end of the link."},"url":{"type":"string","description":"The click-to-chat link (https://wa.me/message/…). Share it, or print its QR code."},"message":{"description":"The text the customer finds already typed; they can edit it before sending.","type":["string","null"]},"qr_image_url":{"description":"QR code image of the link, hosted by WhatsApp. The link can expire: download and keep your own copy for print.","type":["string","null"]},"qr_image_format":{"anyOf":[{"type":"string","enum":["PNG","SVG"]},{"type":"null"}],"description":"PNG or SVG; null when there is no image or its format is not known."},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Workspace channel id (as `GET /v1/channels` lists it)."},"name":{"type":["string","null"]},"phone":{"description":"The WhatsApp number the link opens a chat with.","type":["string","null"]}},"required":["id","name","phone"],"additionalProperties":false},{"type":"null"}],"description":"The WhatsApp number it belongs to."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","code","url","message","qr_image_url","qr_image_format","channel","created_at","updated_at"]},"examples":{"reword":{"summary":"Change the message","value":{"id":"sl-12","code":"4PZQX7M2LCKHA1","url":"https://wa.me/message/4PZQX7M2LCKHA1","message":"Hi! I'd like to book a table","qr_image_url":"https://scontent-bom5-2.xx.fbcdn.net/m1/v/t6/An9_qr4PZQX7M2LCKHA1?ccb=10-5&oe=66F00000","qr_image_format":"PNG","channel":{"id":"301","name":"Main WhatsApp","phone":"+1 555-555-0100"},"created_at":"2026-09-12T10:00:00.000Z","updated_at":"2026-09-13T10:00:00.000Z"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The message breaks a rule (the same ones as **Create a short link**).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The message breaks a rule (the same ones as **Create a short link**).","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The message breaks a rule (the same ones as **Create a short link**).","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No short link with this id in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No short link with this id in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No short link with this id in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"502":{"description":"`upstream_error`: WhatsApp refused the change (`reason: refused_by_whatsapp`).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_error":{"summary":"WhatsApp refused the change (`reason: refused_by_whatsapp`).","value":{"type":"https://dev.wa-api.cloud/errors/upstream_error","title":"A connected service answered unexpectedly","status":502,"detail":"WhatsApp refused the change (`reason: refused_by_whatsapp`).","code":"upstream_error","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_update_short_link","x-platform-ops-path":"/ops/messaging_update_short_link","x-platform-group":"short-links","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"native","x-platform-destructive-verb":null,"x-platform-undo":"Send the old message back.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The message breaks a rule (the same ones as **Create a short link**)."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No short link with this id in your workspace."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_error","status":502,"when":"WhatsApp refused the change (`reason: refused_by_whatsapp`)."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"reword","summary":"Change the message","path":{"short_link_id":"sl-12"},"query":{},"body":{"message":"Hi! I'd like to book a table"},"response":{"status":200,"body":{"id":"sl-12","code":"4PZQX7M2LCKHA1","url":"https://wa.me/message/4PZQX7M2LCKHA1","message":"Hi! I'd like to book a table","qr_image_url":"https://scontent-bom5-2.xx.fbcdn.net/m1/v/t6/An9_qr4PZQX7M2LCKHA1?ccb=10-5&oe=66F00000","qr_image_format":"PNG","channel":{"id":"301","name":"Main WhatsApp","phone":"+1 555-555-0100"},"created_at":"2026-09-12T10:00:00.000Z","updated_at":"2026-09-13T10:00:00.000Z"}}}]},"delete":{"operationId":"deleteShortLink","summary":"Delete a short link","description":"Deletes a short link on WhatsApp for good. **The link stops working, and so does every QR code of it you shared or printed.** A new link gets a new code.","tags":["short-links"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"name":"short_link_id","in":"path","required":true,"description":"The short link id.","schema":{"description":"Short link id.","anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"Deleted.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"deleted":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","deleted"]},"examples":{"delete":{"summary":"Delete a short link","value":{"id":"sl-12","deleted":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No short link with this id in your workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No short link with this id in your workspace.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No short link with this id in your workspace.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"502":{"description":"`upstream_error`: WhatsApp refused to delete it (`reason: refused_by_whatsapp`).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_error":{"summary":"WhatsApp refused to delete it (`reason: refused_by_whatsapp`).","value":{"type":"https://dev.wa-api.cloud/errors/upstream_error","title":"A connected service answered unexpectedly","status":502,"detail":"WhatsApp refused to delete it (`reason: refused_by_whatsapp`).","code":"upstream_error","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"messaging_delete_short_link","x-platform-ops-path":"/ops/messaging_delete_short_link","x-platform-group":"short-links","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":"delete","x-platform-undo":"Cannot be undone. Create a new link; it has a new code and QR code.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No short link with this id in your workspace."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_error","status":502,"when":"WhatsApp refused to delete it (`reason: refused_by_whatsapp`)."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"delete","summary":"Delete a short link","path":{"short_link_id":"sl-12"},"query":{},"response":{"status":200,"body":{"id":"sl-12","deleted":true}}}]}},"/webhooks/endpoints":{"get":{"operationId":"listWebhookEndpoints","summary":"List endpoints","description":"Lists the URLs that receive your events. Signing secrets are never returned here.","tags":["webhooks"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Only this status.","schema":{"description":"Only this status.","type":"string","enum":["active","disabled","paused"]}},{"name":"url_contains","in":"query","required":false,"description":"URL contains this text.","schema":{"description":"URL contains this text.","type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of endpoints.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","description":"active | disabled | paused"},"custom_headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Custom header names; values masked to the last 4 characters."},"consecutive_failures":{"type":"number"},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"signing_secret":{"type":"string","description":"Always masked. The secret is shown once, on create or rotate."},"payload_format":{"type":"string","enum":["data","envelope"],"description":"\"data\" = the event's data object as the body; \"envelope\" = {id, type, version, api_version, occurred_at, company_id, data}."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"subscriptions":{"anyOf":[{"type":"object","properties":{"count":{"type":"number"},"all_active":{"type":"boolean"},"event_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["count","all_active","event_types"],"additionalProperties":false},{"type":"null"}]}},"required":["id","url","description","status","custom_headers","consecutive_failures","disabled_at","disabled_reason","signing_secret","payload_format","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","next_cursor"]},"examples":{"all":{"summary":"All endpoints","value":{"data":[{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null}],"next_cursor":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_list_endpoints","x-platform-ops-path":"/ops/webhooks_list_endpoints","x-platform-group":"webhooks","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"all","summary":"All endpoints","path":{},"query":{},"response":{"status":200,"body":{"data":[{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null}],"next_cursor":null}}}]},"post":{"operationId":"createWebhookEndpoint","summary":"Create an endpoint","description":"Starts sending the chosen events to your URL. The response contains the **signing secret, shown only this once** — store it; you need it to check signatures. Lost it? Rotate it.","tags":["webhooks"],"security":[{"api_key":["webhooks:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"A public https URL. Private and local addresses are refused."},"event_type_ids":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"string","pattern":"^[a-z0-9._-]+\\/[A-Za-z0-9._-]+$","description":"Event type id, e.g. \"contact.created/1\"."},"description":"Event type ids with version, e.g. `contact.created/1`.","x-platform-picker":"event_types"},"description":{"description":"A note for your team.","type":"string","maxLength":500},"custom_headers":{"description":"Extra headers sent with every delivery, e.g. your own auth header. Replaces the whole set; `{}` removes all. Names starting `Webhook-` or `Wc-`, and Content-*, Host, User-Agent, Idempotency-Key and Proxy-* are reserved.","type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":1024}},"payload_format":{"description":"`envelope` (recommended): the wrapped body with id, type, version, api_version, occurred_at and data. `data`: only the event data, the older format. Default for endpoints made with this API: `envelope`.","type":"string","enum":["data","envelope"],"default":"envelope"}},"required":["url","event_type_ids"],"additionalProperties":false},"examples":{"orders":{"summary":"Receive new contacts and closed conversations","value":{"url":"https://hooks.example.com/incoming","event_type_ids":["contact.created/1","conversation.closed/1"],"description":"Order system"}}}}}},"responses":{"201":{"description":"The endpoint and its signing secret (once).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"endpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","description":"active | disabled | paused"},"custom_headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Custom header names; values masked to the last 4 characters."},"consecutive_failures":{"type":"number"},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"signing_secret":{"type":"string","description":"Always masked. The secret is shown once, on create or rotate."},"payload_format":{"type":"string","enum":["data","envelope"],"description":"\"data\" = the event's data object as the body; \"envelope\" = {id, type, version, api_version, occurred_at, company_id, data}."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"subscriptions":{"anyOf":[{"type":"object","properties":{"count":{"type":"number"},"all_active":{"type":"boolean"},"event_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["count","all_active","event_types"],"additionalProperties":false},{"type":"null"}]}},"required":["id","url","description","status","custom_headers","consecutive_failures","disabled_at","disabled_reason","signing_secret","payload_format","created_at","updated_at"],"additionalProperties":false},"signing_secret":{"type":"string"},"warning":{"type":"string"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["endpoint","signing_secret","warning"]},"examples":{"orders":{"summary":"Receive new contacts and closed conversations","value":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"signing_secret":"whsec_EXAMPLE_not_a_real_secret_000000000000","warning":"Store this secret now. It will not be shown again."}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_create_endpoint","x-platform-ops-path":"/ops/webhooks_create_endpoint","x-platform-group":"webhooks","x-platform-scope":"webhooks:write","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"required","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Delete the endpoint.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"orders","summary":"Receive new contacts and closed conversations","path":{},"query":{},"body":{"url":"https://hooks.example.com/incoming","event_type_ids":["contact.created/1","conversation.closed/1"],"description":"Order system"},"response":{"status":201,"body":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"signing_secret":"whsec_EXAMPLE_not_a_real_secret_000000000000","warning":"Store this secret now. It will not be shown again."}}}]}},"/webhooks/endpoints/{endpoint_id}":{"get":{"operationId":"getWebhookEndpoint","summary":"Get an endpoint","description":"Returns one endpoint with every subscription, its status and failure count.","tags":["webhooks"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"description":"The endpoint id.","schema":{"type":"string","pattern":"^ep_[0-9A-HJKMNP-TV-Z]{26}$","description":"Webhook endpoint id (starts with \"ep_\", from `GET /v1/webhooks/endpoints`)."},"x-platform-picker":"endpoints"},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The endpoint.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"endpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","description":"active | disabled | paused"},"custom_headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Custom header names; values masked to the last 4 characters."},"consecutive_failures":{"type":"number"},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"signing_secret":{"type":"string","description":"Always masked. The secret is shown once, on create or rotate."},"payload_format":{"type":"string","enum":["data","envelope"],"description":"\"data\" = the event's data object as the body; \"envelope\" = {id, type, version, api_version, occurred_at, company_id, data}."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"subscriptions":{"anyOf":[{"type":"object","properties":{"count":{"type":"number"},"all_active":{"type":"boolean"},"event_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["count","all_active","event_types"],"additionalProperties":false},{"type":"null"}]}},"required":["id","url","description","status","custom_headers","consecutive_failures","disabled_at","disabled_reason","signing_secret","payload_format","created_at","updated_at"],"additionalProperties":false},"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event_type_id":{"type":"string"},"event_type_name":{"type":"string"},"version":{"type":["string","null"]},"created_at":{"type":["string","null"]}},"required":["id","event_type_id","event_type_name","version","created_at"],"additionalProperties":false}}},"required":["endpoint","subscriptions"]},"examples":{"one":{"summary":"Read one endpoint","value":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"subscriptions":[{"id":"sub_01J8Z6Q5A1B2C3D4E5F6G7H8J9","event_type_id":"contact.created/1","event_type_name":"contact.created","version":"1","created_at":"2026-09-10T12:00:00Z"}]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No endpoint with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No endpoint with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No endpoint with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_get_endpoint","x-platform-ops-path":"/ops/webhooks_get_endpoint","x-platform-group":"webhooks","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No endpoint with this id."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"one","summary":"Read one endpoint","path":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"},"query":{},"response":{"status":200,"body":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"subscriptions":[{"id":"sub_01J8Z6Q5A1B2C3D4E5F6G7H8J9","event_type_id":"contact.created/1","event_type_name":"contact.created","version":"1","created_at":"2026-09-10T12:00:00Z"}]}}}]},"patch":{"operationId":"updateWebhookEndpoint","summary":"Update an endpoint","description":"Changes an endpoint's URL, description or custom headers. Fields you leave out stay as they are. To change events, use **Set subscriptions**.","tags":["webhooks"],"security":[{"api_key":["webhooks:write"]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"description":"The endpoint id.","schema":{"type":"string","pattern":"^ep_[0-9A-HJKMNP-TV-Z]{26}$","description":"Webhook endpoint id (starts with \"ep_\", from `GET /v1/webhooks/endpoints`)."},"x-platform-picker":"endpoints"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"A public https URL. Private and local addresses are refused.","type":"string","minLength":1,"maxLength":2048},"description":{"description":"`null` clears it.","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"custom_headers":{"description":"Extra headers sent with every delivery, e.g. your own auth header. Replaces the whole set; `{}` removes all. Names starting `Webhook-` or `Wc-`, and Content-*, Host, User-Agent, Idempotency-Key and Proxy-* are reserved.","type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":1024}},"payload_format":{"description":"`envelope` (recommended): the wrapped body with id, type, version, api_version, occurred_at and data. `data`: only the event data, the older format. Default for endpoints made with this API: `envelope`.","type":"string","enum":["data","envelope"]}},"additionalProperties":false},"examples":{"move":{"summary":"Move to a new URL","value":{"url":"https://hooks.example.com/v2/incoming"}}}}}},"responses":{"200":{"description":"The endpoint.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"endpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","description":"active | disabled | paused"},"custom_headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Custom header names; values masked to the last 4 characters."},"consecutive_failures":{"type":"number"},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"signing_secret":{"type":"string","description":"Always masked. The secret is shown once, on create or rotate."},"payload_format":{"type":"string","enum":["data","envelope"],"description":"\"data\" = the event's data object as the body; \"envelope\" = {id, type, version, api_version, occurred_at, company_id, data}."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"subscriptions":{"anyOf":[{"type":"object","properties":{"count":{"type":"number"},"all_active":{"type":"boolean"},"event_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["count","all_active","event_types"],"additionalProperties":false},{"type":"null"}]}},"required":["id","url","description","status","custom_headers","consecutive_failures","disabled_at","disabled_reason","signing_secret","payload_format","created_at","updated_at"],"additionalProperties":false},"changed":{"type":"array","items":{"type":"string"}},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["endpoint","changed"]},"examples":{"move":{"summary":"Move to a new URL","value":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/v2/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"changed":["url"]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No endpoint with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No endpoint with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No endpoint with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_update_endpoint","x-platform-ops-path":"/ops/webhooks_update_endpoint","x-platform-group":"webhooks","x-platform-scope":"webhooks:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Send the old values back.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No endpoint with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"move","summary":"Move to a new URL","path":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"},"query":{},"body":{"url":"https://hooks.example.com/v2/incoming"},"response":{"status":200,"body":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/v2/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"changed":["url"]}}}]},"delete":{"operationId":"deleteWebhookEndpoint","summary":"Delete an endpoint","description":"Deletes an endpoint and its subscriptions. Pending deliveries are dropped. Past delivery logs are kept.","tags":["webhooks"],"security":[{"api_key":["webhooks:write"]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"description":"The endpoint id.","schema":{"type":"string","pattern":"^ep_[0-9A-HJKMNP-TV-Z]{26}$","description":"Webhook endpoint id (starts with \"ep_\", from `GET /v1/webhooks/endpoints`)."},"x-platform-picker":"endpoints"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"Deleted.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"deleted":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["id","deleted"]},"examples":{"delete":{"summary":"Delete an endpoint","value":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","deleted":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No endpoint with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No endpoint with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No endpoint with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_delete_endpoint","x-platform-ops-path":"/ops/webhooks_delete_endpoint","x-platform-group":"webhooks","x-platform-scope":"webhooks:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":"delete","x-platform-undo":"Cannot be undone. Create a new endpoint (it gets a new secret).","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No endpoint with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: delete` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"delete","summary":"Delete an endpoint","path":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"},"query":{},"response":{"status":200,"body":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","deleted":true}}}]}},"/webhooks/event-types":{"get":{"operationId":"listWebhookEventTypes","summary":"List event types","description":"The catalog of events an endpoint can subscribe to, such as `contact.created/1`. Each page of this portal under **Events** shows one with its payload.","tags":["webhooks"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"category","in":"query","required":false,"description":"contacts, conversations, messages, broadcasts, sla or taxonomy.","schema":{"description":"contacts, conversations, messages, broadcasts, sla or taxonomy.","type":"string","minLength":1,"maxLength":64}},{"name":"search","in":"query","required":false,"description":"Name contains.","schema":{"description":"Name contains.","type":"string","minLength":1,"maxLength":100}},{"name":"active_only","in":"query","required":false,"description":"Hide retired types.","schema":{"default":true,"description":"Hide retired types.","type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of event types.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Subscribe with this id: \"<type_name>/<version>\"."},"type_name":{"type":"string"},"version":{"type":"string"},"category":{"type":"string"},"display_name":{"type":"string"},"description":{"type":["string","null"]},"active":{"type":"boolean"}},"required":["id","type_name","version","category","display_name","description","active"],"additionalProperties":false}},"total":{"type":"number"},"categories":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"display_name":{"type":"string"},"description":{"type":["string","null"]}},"required":["slug","display_name","description"],"additionalProperties":false}},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","total","next_cursor"]},"examples":{"contacts":{"summary":"Contact events","value":{"data":[{"id":"contact.created/1","type_name":"contact.created","version":"1","category":"contacts","display_name":"Contact created","description":"A new contact was added.","active":true}],"next_cursor":null,"total":1}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_list_event_types","x-platform-ops-path":"/ops/webhooks_list_event_types","x-platform-group":"webhooks","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"contacts","summary":"Contact events","path":{},"query":{"category":"contacts"},"response":{"status":200,"body":{"data":[{"id":"contact.created/1","type_name":"contact.created","version":"1","category":"contacts","display_name":"Contact created","description":"A new contact was added.","active":true}],"next_cursor":null,"total":1}}}]}},"/webhooks/event-types/{event_type}/sample":{"get":{"operationId":"getWebhookEventSample","summary":"Get a sample payload","description":"Returns an example of exactly what your endpoint receives for one event type. Build your receiver against it.","tags":["webhooks"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"event_type","in":"path","required":true,"description":"The event type id.","schema":{"type":"string","minLength":3,"maxLength":120,"pattern":"^[a-z0-9._-]+(\\/[A-Za-z0-9._-]+)?$","description":"The event type id."},"x-platform-picker":"event_types"},{"name":"version","in":"query","required":false,"description":"Payload version. Default: the latest.","schema":{"description":"Payload version. Default: the latest.","type":"string","maxLength":20,"pattern":"^[A-Za-z0-9._-]+$"}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The sample.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"event_type_id":{"type":"string"},"display_name":{"type":"string"},"description":{"type":["string","null"]},"sample":{},"empty":{"type":"boolean"},"note":{"type":"string"}},"required":["event_type_id","display_name","description","sample","empty"]},"examples":{"contact":{"summary":"contact.created","value":{"event_type_id":"contact.created/1","display_name":"Contact created","description":"A new contact was added.","sample":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"contact.created","api_version":"2026-10-01","occurred_at":"2026-09-23T03:02:10Z","company_id":1001,"data":{"id":48213,"company_id":1001,"name":"Jane Doe","phone_number":"15555550123","source":"api"}},"empty":false}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No active event type with this name.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No active event type with this name.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No active event type with this name.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_get_event_sample","x-platform-ops-path":"/ops/webhooks_get_event_sample","x-platform-group":"webhooks","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No active event type with this name."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"contact","summary":"contact.created","path":{"event_type":"contact.created"},"query":{},"response":{"status":200,"body":{"event_type_id":"contact.created/1","display_name":"Contact created","description":"A new contact was added.","sample":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"contact.created","api_version":"2026-10-01","occurred_at":"2026-09-23T03:02:10Z","company_id":1001,"data":{"id":48213,"company_id":1001,"name":"Jane Doe","phone_number":"15555550123","source":"api"}},"empty":false}}}]}},"/webhooks/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List deliveries","description":"Lists delivery attempts, newest first: which event went to which endpoint, and what your endpoint answered. The place to look when events seem missing.","tags":["webhooks"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"endpoint_id","in":"query","required":false,"description":"Only this endpoint.","schema":{"description":"Only this endpoint.","type":"string","pattern":"^ep_[0-9A-HJKMNP-TV-Z]{26}$"},"x-platform-picker":"endpoints"},{"name":"status","in":"query","required":false,"description":"Only these statuses.","schema":{"description":"Only these statuses.","minItems":1,"maxItems":4,"type":"array","items":{"type":"string","enum":["pending","succeeded","failed","expired"]}},"style":"form","explode":true},{"name":"response_class","in":"query","required":false,"description":"`non2xx` includes no response at all.","schema":{"description":"`non2xx` includes no response at all.","type":"string","enum":["2xx","non2xx"]}},{"name":"from","in":"query","required":false,"description":"Start of the window (ISO 8601 with offset). Default: 7 days ago. Kept 30 days.","schema":{"description":"Start of the window (ISO 8601 with offset). Default: 7 days ago. Kept 30 days.","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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"to","in":"query","required":false,"description":"End of the window. Default: now.","schema":{"description":"End of the window. Default: now.","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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of deliveries.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_id":{"type":["string","null"]},"status":{"type":"string","description":"pending | succeeded | failed | expired"},"attempt":{"type":"number"},"response_status":{"type":["number","null"]},"latency_ms":{"type":["number","null"]},"created_at":{"type":["string","null"]}},"required":["id","endpoint_id","event_id","status","attempt","response_status","latency_ms","created_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","next_cursor"]},"examples":{"failed":{"summary":"Failed deliveries this week","value":{"data":[{"id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"failed","attempt":2,"response_status":500,"latency_ms":812,"created_at":"2026-09-23T03:02:11Z"}],"next_cursor":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_list_deliveries","x-platform-ops-path":"/ops/webhooks_list_deliveries","x-platform-group":"webhooks","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"failed","summary":"Failed deliveries this week","path":{},"query":{"status":["failed"]},"response":{"status":200,"body":{"data":[{"id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"failed","attempt":2,"response_status":500,"latency_ms":812,"created_at":"2026-09-23T03:02:11Z"}],"next_cursor":null}}}]}},"/webhooks/deliveries/{delivery_id}":{"get":{"operationId":"getWebhookDelivery","summary":"Get a delivery","description":"Explains one delivery: status, HTTP code, latency, error, next retry, the headers we sent (signature masked) and what your endpoint answered.","tags":["webhooks"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"delivery_id","in":"path","required":true,"description":"The delivery id.","schema":{"type":"string","pattern":"^del_[0-9A-HJKMNP-TV-Z]{26}$","description":"Delivery id (starts with \"del_\", from `GET /v1/webhooks/deliveries`)."}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The delivery.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_id":{"type":["string","null"]},"status":{"type":"string","description":"pending | succeeded | failed | expired"},"attempt":{"type":"number"},"response_status":{"type":["number","null"]},"latency_ms":{"type":["number","null"]},"created_at":{"type":["string","null"]},"error_message":{"type":["string","null"]},"next_attempt_at":{"type":["string","null"]},"request_headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Signature and custom header values are masked."},"response_headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"response_body":{"type":["string","null"]},"response_body_truncated":{"type":"boolean"},"request_body":{"type":["string","null"]},"request_body_truncated":{"type":"boolean"},"request_body_available":{"type":["boolean","null"]},"attempts":{"description":"Every attempt of the same event to the same endpoint, oldest first.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_id":{"type":["string","null"]},"status":{"type":"string","description":"pending | succeeded | failed | expired"},"attempt":{"type":"number"},"response_status":{"type":["number","null"]},"latency_ms":{"type":["number","null"]},"created_at":{"type":["string","null"]}},"required":["id","endpoint_id","event_id","status","attempt","response_status","latency_ms","created_at"],"additionalProperties":false}},"attempts_note":{"type":"string"}},"required":["id","endpoint_id","event_id","status","attempt","response_status","latency_ms","created_at","error_message","next_attempt_at","request_headers","response_headers","response_body","response_body_truncated","request_body_available"]},"examples":{"one":{"summary":"Why did this fail?","value":{"id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"failed","attempt":2,"response_status":500,"latency_ms":812,"created_at":"2026-09-23T03:02:11Z","error_message":"HTTP 500 from receiver","next_attempt_at":"2026-09-23T03:07:11Z","request_headers":{"Content-Type":"application/json","Webhook-Signature":"t=1758596531,v1=••••"},"response_headers":{"content-type":"text/plain"},"response_body":"Internal Server Error","attempts":[{"id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"failed","attempt":1,"response_status":500,"latency_ms":812,"created_at":"2026-09-23T03:02:10Z"},{"id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"failed","attempt":2,"response_status":500,"latency_ms":812,"created_at":"2026-09-23T03:02:11Z"}],"response_body_truncated":false,"request_body_available":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No delivery with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No delivery with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No delivery with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_get_delivery","x-platform-ops-path":"/ops/webhooks_get_delivery","x-platform-group":"webhooks","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No delivery with this id."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"one","summary":"Why did this fail?","path":{"delivery_id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB"},"query":{},"response":{"status":200,"body":{"id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"failed","attempt":2,"response_status":500,"latency_ms":812,"created_at":"2026-09-23T03:02:11Z","error_message":"HTTP 500 from receiver","next_attempt_at":"2026-09-23T03:07:11Z","request_headers":{"Content-Type":"application/json","Webhook-Signature":"t=1758596531,v1=••••"},"response_headers":{"content-type":"text/plain"},"response_body":"Internal Server Error","attempts":[{"id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"failed","attempt":1,"response_status":500,"latency_ms":812,"created_at":"2026-09-23T03:02:10Z"},{"id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"failed","attempt":2,"response_status":500,"latency_ms":812,"created_at":"2026-09-23T03:02:11Z"}],"response_body_truncated":false,"request_body_available":null}}}]}},"/webhooks/events":{"get":{"operationId":"listWebhookEvents","summary":"List events","description":"Lists the events that happened in your workspace, newest first. Events are kept for 30 days.","tags":["webhooks"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"event_type_id","in":"query","required":false,"description":"Only this type, e.g. `contact.created/1`.","schema":{"description":"Only this type, e.g. `contact.created/1`.","type":"string","pattern":"^[a-z0-9._-]+\\/[A-Za-z0-9._-]+$"},"x-platform-picker":"event_types"},{"name":"endpoint_id","in":"query","required":false,"description":"Only events sent to this endpoint.","schema":{"description":"Only events sent to this endpoint.","type":"string","pattern":"^ep_[0-9A-HJKMNP-TV-Z]{26}$"},"x-platform-picker":"endpoints"},{"name":"from","in":"query","required":false,"description":"Start of the window (ISO 8601 with offset). Default: 7 days ago. Kept 30 days.","schema":{"description":"Start of the window (ISO 8601 with offset). Default: 7 days ago. Kept 30 days.","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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"to","in":"query","required":false,"description":"End of the window. Default: now.","schema":{"description":"End of the window. Default: now.","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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of events.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event_type_id":{"type":"string"},"event_type_name":{"type":"string"},"occurred_at":{"type":["string","null"]},"created_at":{"type":["string","null"]}},"required":["id","event_type_id","event_type_name","occurred_at","created_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","next_cursor"]},"examples":{"contacts":{"summary":"New contacts","value":{"data":[{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","event_type_id":"contact.created/1","event_type_name":"contact.created","occurred_at":"2026-09-23T03:02:10Z","created_at":"2026-09-23T03:02:10Z"}],"next_cursor":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_list_events","x-platform-ops-path":"/ops/webhooks_list_events","x-platform-group":"webhooks","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"contacts","summary":"New contacts","path":{},"query":{"event_type_id":"contact.created/1"},"response":{"status":200,"body":{"data":[{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","event_type_id":"contact.created/1","event_type_name":"contact.created","occurred_at":"2026-09-23T03:02:10Z","created_at":"2026-09-23T03:02:10Z"}],"next_cursor":null}}}]}},"/webhooks/events/{event_id}":{"get":{"operationId":"getWebhookEvent","summary":"Get an event","description":"Returns one event with the exact payload your endpoints received, and every delivery attempt.","tags":["webhooks"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"event_id","in":"path","required":true,"description":"The event id.","schema":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Webhook event id (starts with \"evt_\", from `GET /v1/webhooks/events`)."}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The event.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"event_type_id":{"type":"string"},"event_type_name":{"type":"string"},"occurred_at":{"type":["string","null"]},"created_at":{"type":["string","null"]},"payload":{},"payload_truncated":{"type":"boolean"},"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_id":{"type":["string","null"]},"status":{"type":"string","description":"pending | succeeded | failed | expired"},"attempt":{"type":"number"},"response_status":{"type":["number","null"]},"latency_ms":{"type":["number","null"]},"created_at":{"type":["string","null"]}},"required":["id","endpoint_id","event_id","status","attempt","response_status","latency_ms","created_at"],"additionalProperties":false}}},"required":["id","event_type_id","event_type_name","occurred_at","created_at","deliveries"]},"examples":{"one":{"summary":"Read an event","value":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","event_type_id":"contact.created/1","event_type_name":"contact.created","occurred_at":"2026-09-23T03:02:10Z","created_at":"2026-09-23T03:02:10Z","payload":{"id":48213,"company_id":1001,"name":"Jane Doe","phone_number":"15555550123","source":"api"},"deliveries":[{"id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"failed","attempt":2,"response_status":500,"latency_ms":812,"created_at":"2026-09-23T03:02:11Z"}]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No event with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No event with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No event with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_get_event","x-platform-ops-path":"/ops/webhooks_get_event","x-platform-group":"webhooks","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No event with this id."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"one","summary":"Read an event","path":{"event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC"},"query":{},"response":{"status":200,"body":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","event_type_id":"contact.created/1","event_type_name":"contact.created","occurred_at":"2026-09-23T03:02:10Z","created_at":"2026-09-23T03:02:10Z","payload":{"id":48213,"company_id":1001,"name":"Jane Doe","phone_number":"15555550123","source":"api"},"deliveries":[{"id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"failed","attempt":2,"response_status":500,"latency_ms":812,"created_at":"2026-09-23T03:02:11Z"}]}}}]}},"/webhooks/endpoints/{endpoint_id}/enable":{"post":{"operationId":"enableWebhookEndpoint","summary":"Turn an endpoint on","description":"Turns a disabled or paused endpoint back on and resets its failure count. Events from while it was off are not sent later — replay them if you need them.","tags":["webhooks"],"security":[{"api_key":["webhooks:write"]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"description":"The endpoint id.","schema":{"type":"string","pattern":"^ep_[0-9A-HJKMNP-TV-Z]{26}$","description":"Webhook endpoint id (starts with \"ep_\", from `GET /v1/webhooks/endpoints`)."},"x-platform-picker":"endpoints"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"The endpoint.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"endpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","description":"active | disabled | paused"},"custom_headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Custom header names; values masked to the last 4 characters."},"consecutive_failures":{"type":"number"},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"signing_secret":{"type":"string","description":"Always masked. The secret is shown once, on create or rotate."},"payload_format":{"type":"string","enum":["data","envelope"],"description":"\"data\" = the event's data object as the body; \"envelope\" = {id, type, version, api_version, occurred_at, company_id, data}."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"subscriptions":{"anyOf":[{"type":"object","properties":{"count":{"type":"number"},"all_active":{"type":"boolean"},"event_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["count","all_active","event_types"],"additionalProperties":false},{"type":"null"}]}},"required":["id","url","description","status","custom_headers","consecutive_failures","disabled_at","disabled_reason","signing_secret","payload_format","created_at","updated_at"],"additionalProperties":false},"changed":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["endpoint","changed"]},"examples":{"on":{"summary":"Turn it back on","value":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"changed":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No endpoint with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No endpoint with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No endpoint with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_enable_endpoint","x-platform-ops-path":"/ops/webhooks_enable_endpoint","x-platform-group":"webhooks","x-platform-scope":"webhooks:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"none","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Turn it off again.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No endpoint with this id."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"on","summary":"Turn it back on","path":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"},"query":{},"response":{"status":200,"body":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"changed":true}}}]}},"/webhooks/endpoints/{endpoint_id}/disable":{"post":{"operationId":"disableWebhookEndpoint","summary":"Turn an endpoint off","description":"Pauses deliveries to one endpoint. Nothing is deleted. Events that happen while it is off are not delivered later.","tags":["webhooks"],"security":[{"api_key":["webhooks:write"]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"description":"The endpoint id.","schema":{"type":"string","pattern":"^ep_[0-9A-HJKMNP-TV-Z]{26}$","description":"Webhook endpoint id (starts with \"ep_\", from `GET /v1/webhooks/endpoints`)."},"x-platform-picker":"endpoints"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"The endpoint.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"endpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","description":"active | disabled | paused"},"custom_headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Custom header names; values masked to the last 4 characters."},"consecutive_failures":{"type":"number"},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"signing_secret":{"type":"string","description":"Always masked. The secret is shown once, on create or rotate."},"payload_format":{"type":"string","enum":["data","envelope"],"description":"\"data\" = the event's data object as the body; \"envelope\" = {id, type, version, api_version, occurred_at, company_id, data}."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"subscriptions":{"anyOf":[{"type":"object","properties":{"count":{"type":"number"},"all_active":{"type":"boolean"},"event_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["count","all_active","event_types"],"additionalProperties":false},{"type":"null"}]}},"required":["id","url","description","status","custom_headers","consecutive_failures","disabled_at","disabled_reason","signing_secret","payload_format","created_at","updated_at"],"additionalProperties":false},"changed":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["endpoint","changed"]},"examples":{"off":{"summary":"Pause deliveries","value":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"disabled","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"changed":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No endpoint with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No endpoint with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No endpoint with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_disable_endpoint","x-platform-ops-path":"/ops/webhooks_disable_endpoint","x-platform-group":"webhooks","x-platform-scope":"webhooks:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"none","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Turn it on again (missed events can be replayed).","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No endpoint with this id."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"off","summary":"Pause deliveries","path":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"},"query":{},"response":{"status":200,"body":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"disabled","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"changed":true}}}]}},"/webhooks/endpoints/{endpoint_id}/rotate-secret":{"post":{"operationId":"rotateWebhookSecret","summary":"Rotate the signing secret","description":"Makes a new signing secret, shown only in this response. The old one keeps working for **24 hours** (deliveries carry both signatures), then stops. Switch your receiver to the new one in time.","tags":["webhooks"],"security":[{"api_key":["webhooks:write"]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"description":"The endpoint id.","schema":{"type":"string","pattern":"^ep_[0-9A-HJKMNP-TV-Z]{26}$","description":"Webhook endpoint id (starts with \"ep_\", from `GET /v1/webhooks/endpoints`)."},"x-platform-picker":"endpoints"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"The new secret (once).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"endpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","description":"active | disabled | paused"},"custom_headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Custom header names; values masked to the last 4 characters."},"consecutive_failures":{"type":"number"},"disabled_at":{"type":["string","null"]},"disabled_reason":{"type":["string","null"]},"signing_secret":{"type":"string","description":"Always masked. The secret is shown once, on create or rotate."},"payload_format":{"type":"string","enum":["data","envelope"],"description":"\"data\" = the event's data object as the body; \"envelope\" = {id, type, version, api_version, occurred_at, company_id, data}."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"subscriptions":{"anyOf":[{"type":"object","properties":{"count":{"type":"number"},"all_active":{"type":"boolean"},"event_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["count","all_active","event_types"],"additionalProperties":false},{"type":"null"}]}},"required":["id","url","description","status","custom_headers","consecutive_failures","disabled_at","disabled_reason","signing_secret","payload_format","created_at","updated_at"],"additionalProperties":false},"signing_secret":{"type":"string"},"old_secret_valid_until":{"type":"string"},"warning":{"type":"string"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["endpoint","signing_secret","old_secret_valid_until","warning"]},"examples":{"rotate":{"summary":"Rotate after a leak","value":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"signing_secret":"whsec_EXAMPLE_not_a_real_secret_111111111111","old_secret_valid_until":"2026-09-25T10:00:00Z","warning":"Store this secret now. It will not be shown again."}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No endpoint with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No endpoint with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No endpoint with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: rotate` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: rotate` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: rotate` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_rotate_secret","x-platform-ops-path":"/ops/webhooks_rotate_secret","x-platform-group":"webhooks","x-platform-scope":"webhooks:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"required","x-platform-dry-run":"checks","x-platform-destructive-verb":"rotate","x-platform-undo":"Cannot be undone after 24 hours. Before then, both secrets work.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No endpoint with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: rotate` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"rotate","summary":"Rotate after a leak","path":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"},"query":{},"response":{"status":200,"body":{"endpoint":{"id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","url":"https://hooks.example.com/incoming","description":"Order system","status":"active","custom_headers":{"X-Hook-Token":"••••9f2a"},"payload_format":"envelope","consecutive_failures":0,"disabled_reason":null,"signing_secret":"whsec_••••••••","created_at":"2026-09-10T12:00:00Z","updated_at":"2026-09-10T12:00:00Z","disabled_at":null},"signing_secret":"whsec_EXAMPLE_not_a_real_secret_111111111111","old_secret_valid_until":"2026-09-25T10:00:00Z","warning":"Store this secret now. It will not be shown again."}}}]}},"/webhooks/endpoints/{endpoint_id}/subscriptions":{"put":{"operationId":"setWebhookSubscriptions","summary":"Set subscriptions","description":"**Replaces** the full list of events an endpoint receives: types you leave out are unsubscribed. Read the current list with **Get an endpoint** first.","tags":["webhooks"],"security":[{"api_key":["webhooks:write"]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"description":"The endpoint id.","schema":{"type":"string","pattern":"^ep_[0-9A-HJKMNP-TV-Z]{26}$","description":"Webhook endpoint id (starts with \"ep_\", from `GET /v1/webhooks/endpoints`)."},"x-platform-picker":"endpoints"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_type_ids":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"string","pattern":"^[a-z0-9._-]+\\/[A-Za-z0-9._-]+$","description":"Event type id, e.g. \"conversation.closed/1\"."},"description":"Event type ids with version, e.g. `contact.created/1`.","x-platform-picker":"event_types"}},"required":["event_type_ids"],"additionalProperties":false},"examples":{"helpdesk":{"summary":"Listen to conversation events","value":{"event_type_ids":["conversation.created/1","conversation.assigned/1","conversation.closed/1"]}}}}}},"responses":{"200":{"description":"The new set.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"endpoint_id":{"type":"string"},"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event_type_id":{"type":"string"},"event_type_name":{"type":"string"},"version":{"type":["string","null"]},"created_at":{"type":["string","null"]}},"required":["id","event_type_id","event_type_name","version","created_at"],"additionalProperties":false}},"added":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["endpoint_id","subscriptions","added","removed"]},"examples":{"helpdesk":{"summary":"Listen to conversation events","value":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","subscriptions":[{"id":"sub_01J8Z6Q5A1B2C3D4E5F6G7H8J9","event_type_id":"conversation.created/1","event_type_name":"conversation.created","version":"1","created_at":"2026-09-24T10:00:00Z"}],"added":["conversation.created/1","conversation.assigned/1"],"removed":["contact.created/1"]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No endpoint with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No endpoint with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No endpoint with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_set_subscriptions","x-platform-ops-path":"/ops/webhooks_set_subscriptions","x-platform-group":"webhooks","x-platform-scope":"webhooks:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Send the old list back.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No endpoint with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"helpdesk","summary":"Listen to conversation events","path":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"},"query":{},"body":{"event_type_ids":["conversation.created/1","conversation.assigned/1","conversation.closed/1"]},"response":{"status":200,"body":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","subscriptions":[{"id":"sub_01J8Z6Q5A1B2C3D4E5F6G7H8J9","event_type_id":"conversation.created/1","event_type_name":"conversation.created","version":"1","created_at":"2026-09-24T10:00:00Z"}],"added":["conversation.created/1","conversation.assigned/1"],"removed":["contact.created/1"]}}}]}},"/webhooks/endpoints/{endpoint_id}/test":{"post":{"operationId":"sendWebhookTest","summary":"Send a test event","description":"Sends one signed test event to your endpoint, so you can check your receiver. It looks exactly like a real event, with sample data unless you pass your own.","tags":["webhooks"],"security":[{"api_key":["webhooks:write"]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"description":"The endpoint id.","schema":{"type":"string","pattern":"^ep_[0-9A-HJKMNP-TV-Z]{26}$","description":"The endpoint id."},"x-platform-picker":"endpoints"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_type_id":{"type":"string","pattern":"^[a-z0-9._-]+\\/[A-Za-z0-9._-]+$","description":"e.g. `contact.created/1`.","x-platform-picker":"event_types"},"payload":{"description":"Your own `data` object. Default: the sample.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["event_type_id"],"additionalProperties":false},"examples":{"test":{"summary":"Send a test contact.created","value":{"event_type_id":"contact.created/1"}}}}}},"responses":{"202":{"description":"Queued.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"event_id":{"type":"string"},"endpoint_id":{"type":"string"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["event_id","endpoint_id"]},"examples":{"test":{"summary":"Send a test contact.created","value":{"event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No endpoint with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No endpoint with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No endpoint with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_send_test","x-platform-ops-path":"/ops/webhooks_send_test","x-platform-group":"webhooks","x-platform-scope":"webhooks:write","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"required","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo; your receiver gets one extra event.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No endpoint with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"test","summary":"Send a test contact.created","path":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"},"query":{},"body":{"event_type_id":"contact.created/1"},"response":{"status":202,"body":{"event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"}}}]}},"/webhooks/deliveries/{delivery_id}/retry":{"post":{"operationId":"retryWebhookDelivery","summary":"Retry a delivery now","description":"Re-sends one failed or expired delivery right away, skipping the backoff. Your receiver gets the same event again (same `Webhook-Id`), so it must handle duplicates.","tags":["webhooks"],"security":[{"api_key":["webhooks:write"]}],"parameters":[{"name":"delivery_id","in":"path","required":true,"description":"The delivery id.","schema":{"type":"string","pattern":"^del_[0-9A-HJKMNP-TV-Z]{26}$","description":"Delivery id (starts with \"del_\", from `GET /v1/webhooks/deliveries`)."}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"202":{"description":"The new attempt.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"retried_from":{"type":"string"},"delivery":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_id":{"type":["string","null"]},"status":{"type":"string","description":"pending | succeeded | failed | expired"},"attempt":{"type":"number"},"response_status":{"type":["number","null"]},"latency_ms":{"type":["number","null"]},"created_at":{"type":["string","null"]}},"required":["id","endpoint_id","event_id","status","attempt","response_status","latency_ms","created_at"],"additionalProperties":false},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["retried_from","delivery"]},"examples":{"retry":{"summary":"Retry after fixing your server","value":{"retried_from":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","delivery":{"id":"del_01J8Z9D3F6J0M5N7Q9S2T4W6YC","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"pending","attempt":3,"response_status":null,"latency_ms":null,"created_at":"2026-09-23T03:02:11Z"}}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No delivery with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No delivery with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No delivery with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Only failed or expired deliveries can be retried. Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Only failed or expired deliveries can be retried. Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Only failed or expired deliveries can be retried. Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_retry_delivery","x-platform-ops-path":"/ops/webhooks_retry_delivery","x-platform-group":"webhooks","x-platform-scope":"webhooks:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"required","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo; your receiver gets the event again.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No delivery with this id."},{"code":"conflict","status":409,"when":"Only failed or expired deliveries can be retried. Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"retry","summary":"Retry after fixing your server","path":{"delivery_id":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB"},"query":{},"response":{"status":202,"body":{"retried_from":"del_01J8Z7C2E5H9K4M6P8R1S3V5XB","delivery":{"id":"del_01J8Z9D3F6J0M5N7Q9S2T4W6YC","endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA","event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","status":"pending","attempt":3,"response_status":null,"latency_ms":null,"created_at":"2026-09-23T03:02:11Z"}}}}]}},"/webhooks/events/{event_id}/replay":{"post":{"operationId":"replayWebhookEvent","summary":"Replay an event","description":"Delivers a past event again, with its original payload, to one endpoint — or to every endpoint subscribed now if you leave `endpoint_id` out. Receivers get a duplicate and may act on it again. Only events from the last 30 days.","tags":["webhooks"],"security":[{"api_key":["webhooks:write"]}],"parameters":[{"name":"event_id","in":"path","required":true,"description":"The event id.","schema":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event to replay (evt_…)."}},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint_id":{"description":"Only this endpoint. Leave out for every subscribed endpoint.","type":"string","pattern":"^ep_[0-9A-HJKMNP-TV-Z]{26}$","x-platform-picker":"endpoints"}},"additionalProperties":false},"examples":{"one":{"summary":"Replay to one endpoint","value":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"}}}}}},"responses":{"202":{"description":"Queued.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"event_id":{"type":"string"},"queued_deliveries":{"type":"number"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["event_id","queued_deliveries"]},"examples":{"one":{"summary":"Replay to one endpoint","value":{"event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","queued_deliveries":1}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No event with this id, or it is older than 30 days.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No event with this id, or it is older than 30 days.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No event with this id, or it is older than 30 days.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: replay` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: replay` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: replay` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"webhooks_replay_event","x-platform-ops-path":"/ops/webhooks_replay_event","x-platform-group":"webhooks","x-platform-scope":"webhooks:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"required","x-platform-dry-run":"checks","x-platform-destructive-verb":"replay","x-platform-undo":"Cannot be undone: receivers get the event again.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No event with this id, or it is older than 30 days."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: replay` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"one","summary":"Replay to one endpoint","path":{"event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC"},"query":{},"body":{"endpoint_id":"ep_01J8Z6Q4M9W2X7K3B5N1R0T8YA"},"response":{"status":202,"body":{"event_id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","queued_deliveries":1}}}]}},"/conversations":{"get":{"operationId":"listConversations","summary":"List conversations","description":"Finds inbox conversations, newest activity first. Filter by state, assignee, tags, channel or whether the customer is waiting for a reply.\n\nEach conversation has a `window`: whether a free-form reply can be sent right now (`open`), and until when (`closes_at`, UTC). It is decided exactly as a reply is, so `open: false` means a reply would be refused with `window_closed` (send an approved template instead). `whatsapp_window_expires_at` is the raw stored time, kept for compatibility: decide with `window`.","tags":["inbox"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"query","in":"query","required":false,"description":"Contact name or phone contains.","schema":{"description":"Contact name or phone contains.","type":"string","minLength":1,"maxLength":255}},{"name":"state","in":"query","required":false,"description":"open or closed.","schema":{"description":"open or closed.","type":"string","enum":["open","closed"]}},{"name":"assigned","in":"query","required":false,"description":"`false` = the unassigned queue.","schema":{"description":"`false` = the unassigned queue.","type":"boolean"}},{"name":"channel_id","in":"query","required":false,"description":"Only this channel.","schema":{"description":"Only this channel.","type":"string","pattern":"^\\d{1,19}$"},"x-platform-picker":"channels"},{"name":"reply_status","in":"query","required":false,"description":"`incoming_no_reply` = the customer is waiting.","schema":{"description":"`incoming_no_reply` = the customer is waiting.","type":"string","enum":["incoming_no_reply","outgoing_no_response"]}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of conversations.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","description":"open | closed"},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"phone":{"type":["string","null"]},"dnd_enabled":{"type":"boolean"},"groups":{"type":"array","items":{"type":"string"}}},"required":["id","name","phone","dnd_enabled","groups"],"additionalProperties":false},{"type":"null"}],"description":"null when the contact was deleted."},"channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"type":{"type":["string","null"]}},"required":["id","name","type"],"additionalProperties":false},"assignee":{"anyOf":[{"type":"object","properties":{"staff_id":{"type":"string"},"name":{"type":["string","null"]}},"required":["staff_id","name"],"additionalProperties":false},{"type":"null"}]},"team_id":{"type":["string","null"]},"assigned_at":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"starred":{"type":"boolean"},"unread_count":{"type":"number"},"reply_status":{"description":"incoming_no_reply = customer is waiting; outgoing_no_response = waiting on the customer.","type":["string","null"]},"sla":{"anyOf":[{"type":"object","properties":{"status":{"type":"string"},"next_due_at":{"type":["string","null"]},"next_due_metric":{"type":["string","null"]},"policy":{"type":["string","null"]}},"required":["status","next_due_at","next_due_metric","policy"],"additionalProperties":false},{"type":"null"}]},"reminder_at":{"type":["string","null"]},"whatsapp_window_expires_at":{"description":"Raw window end as stored, kept for compatibility. Use `window` to decide whether a free-form reply can be sent.","type":["string","null"]},"window":{"type":"object","properties":{"applies":{"type":"boolean","description":"true on channels with a reply window (WhatsApp, Instagram, Messenger, TikTok); false on web chat and custom channels."},"open":{"type":"boolean","description":"true = a free-form reply can be sent now (always true when the window does not apply). false = only an approved template reaches the customer."},"kind":{"description":"service (24 h), free_entry (72 h after an ad), standard, tiktok (48 h), web.","type":["string","null"]},"closes_at":{"description":"Open window: when it closes (UTC ISO-8601); null when unknown or when no window applies.","type":["string","null"]},"closed_at":{"description":"Closed window: when it closed (UTC); null when the customer never opened one.","type":["string","null"]},"reason":{"anyOf":[{"type":"string","enum":["no_window","expired","never_opened"]},{"type":"null"}],"description":"Why: no_window (the channel has none), expired (it closed at closedAt), never_opened (no customer message on this channel yet); null while open."}},"required":["applies","open","kind","closes_at","closed_at","reason"],"additionalProperties":false,"description":"The reply window, decided exactly as a send decides it. The source of truth for \"can I reply free-form now\"."},"bot_active":{"type":"boolean"},"last_message":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":["string","null"]},"type":{"type":"string","description":"TEXT, IMAGE, VIDEO, AUDIO, DOCUMENT, STICKER, LOCATION, TEMPLATE, INTERACTIVE, ORDER, CONTACTS, SYSTEM"},"direction":{"type":"string","enum":["inbound","outbound","system"]},"status":{"type":"string","description":"received (inbound) | pending | sent | delivered | read | failed | system"},"text":{"description":"Message text, or the caption for media. Media files/URLs are never included.","type":["string","null"]},"text_truncated":{"type":"boolean"},"has_media":{"type":"boolean"},"from":{"anyOf":[{"type":"object","properties":{"staff_id":{"type":["string","null"]},"staff_name":{"type":["string","null"]},"bot":{"type":"boolean"}},"required":["staff_id","staff_name","bot"],"additionalProperties":false},{"type":"null"}],"description":"Who sent an outbound message (staff or bot); null for inbound."},"reply_to_id":{"type":["string","null"]},"error":{"type":["string","null"]},"created_at":{"type":["string","null"]}},"required":["id","conversation_id","type","direction","status","text","text_truncated","has_media","from","reply_to_id","error","created_at"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","state","contact","channel","assignee","team_id","assigned_at","tags","starred","unread_count","reply_status","sla","reminder_at","whatsapp_window_expires_at","window","bot_active","last_message","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","next_cursor"]},"examples":{"waiting":{"summary":"Customers waiting for a reply","value":{"data":[{"id":"77410","state":"open","contact":{"id":"48213","name":"Jane Doe","phone":"+15555550123","dnd_enabled":false,"groups":[]},"channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"assignee":null,"team_id":null,"tags":[{"id":"4","name":"new-lead"}],"unread_count":2,"reply_status":"incoming_no_reply","whatsapp_window_expires_at":"2026-09-25T09:12:00Z","window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null,"reason":null},"last_message":{"id":"5501234","type":"TEXT","direction":"inbound","status":"received","text":"Hi, is the blue one in stock?","created_at":"2026-09-24T09:12:00Z","conversation_id":null,"text_truncated":false,"has_media":false,"from":null,"reply_to_id":null,"error":null},"created_at":"2026-09-24T09:11:40Z","updated_at":"2026-09-24T09:12:00Z","assigned_at":null,"starred":false,"sla":null,"reminder_at":null,"bot_active":false}],"next_cursor":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_search_conversations","x-platform-ops-path":"/ops/inbox_search_conversations","x-platform-group":"inbox","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"waiting","summary":"Customers waiting for a reply","path":{},"query":{"state":"open","reply_status":"incoming_no_reply"},"response":{"status":200,"body":{"data":[{"id":"77410","state":"open","contact":{"id":"48213","name":"Jane Doe","phone":"+15555550123","dnd_enabled":false,"groups":[]},"channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"assignee":null,"team_id":null,"tags":[{"id":"4","name":"new-lead"}],"unread_count":2,"reply_status":"incoming_no_reply","whatsapp_window_expires_at":"2026-09-25T09:12:00Z","window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null,"reason":null},"last_message":{"id":"5501234","type":"TEXT","direction":"inbound","status":"received","text":"Hi, is the blue one in stock?","created_at":"2026-09-24T09:12:00Z","conversation_id":null,"text_truncated":false,"has_media":false,"from":null,"reply_to_id":null,"error":null},"created_at":"2026-09-24T09:11:40Z","updated_at":"2026-09-24T09:12:00Z","assigned_at":null,"starred":false,"sla":null,"reminder_at":null,"bot_active":false}],"next_cursor":null}}}]}},"/conversations/{conversation_id}":{"get":{"operationId":"getConversation","summary":"Get a conversation and its 24-hour window","description":"Returns one conversation with its contact, assignee, tags, the reply window and the latest messages. Reading it does not mark anything as read.\n\n`window` is the source of truth for replying: `applies` is true on WhatsApp, Instagram, Messenger and TikTok (false on web chat, where `open` is always true); `open` says whether a free-form reply can be sent now, decided exactly as the reply itself is; `closes_at` (UTC) is when an open window closes, or null when that is not known; a closed window has a `reason`: `expired` (it closed at `closed_at`) or `never_opened` (the customer has not written on this channel). To check the window alone, ask with `last_messages=0`.","tags":["inbox"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"Conversation id (from `GET /v1/conversations`)."},"x-platform-picker":"conversations"},{"name":"last_messages","in":"query","required":false,"description":"How many recent messages to include (0–20).","schema":{"default":5,"description":"How many recent messages to include (0–20).","type":"integer","minimum":0,"maximum":20}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The conversation.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversation":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","description":"open | closed"},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"phone":{"type":["string","null"]},"dnd_enabled":{"type":"boolean"},"groups":{"type":"array","items":{"type":"string"}}},"required":["id","name","phone","dnd_enabled","groups"],"additionalProperties":false},{"type":"null"}],"description":"null when the contact was deleted."},"channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"type":{"type":["string","null"]}},"required":["id","name","type"],"additionalProperties":false},"assignee":{"anyOf":[{"type":"object","properties":{"staff_id":{"type":"string"},"name":{"type":["string","null"]}},"required":["staff_id","name"],"additionalProperties":false},{"type":"null"}]},"team_id":{"type":["string","null"]},"assigned_at":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"starred":{"type":"boolean"},"unread_count":{"type":"number"},"reply_status":{"description":"incoming_no_reply = customer is waiting; outgoing_no_response = waiting on the customer.","type":["string","null"]},"sla":{"anyOf":[{"type":"object","properties":{"status":{"type":"string"},"next_due_at":{"type":["string","null"]},"next_due_metric":{"type":["string","null"]},"policy":{"type":["string","null"]}},"required":["status","next_due_at","next_due_metric","policy"],"additionalProperties":false},{"type":"null"}]},"reminder_at":{"type":["string","null"]},"whatsapp_window_expires_at":{"description":"Raw window end as stored, kept for compatibility. Use `window` to decide whether a free-form reply can be sent.","type":["string","null"]},"window":{"type":"object","properties":{"applies":{"type":"boolean","description":"true on channels with a reply window (WhatsApp, Instagram, Messenger, TikTok); false on web chat and custom channels."},"open":{"type":"boolean","description":"true = a free-form reply can be sent now (always true when the window does not apply). false = only an approved template reaches the customer."},"kind":{"description":"service (24 h), free_entry (72 h after an ad), standard, tiktok (48 h), web.","type":["string","null"]},"closes_at":{"description":"Open window: when it closes (UTC ISO-8601); null when unknown or when no window applies.","type":["string","null"]},"closed_at":{"description":"Closed window: when it closed (UTC); null when the customer never opened one.","type":["string","null"]},"reason":{"anyOf":[{"type":"string","enum":["no_window","expired","never_opened"]},{"type":"null"}],"description":"Why: no_window (the channel has none), expired (it closed at closedAt), never_opened (no customer message on this channel yet); null while open."}},"required":["applies","open","kind","closes_at","closed_at","reason"],"additionalProperties":false,"description":"The reply window, decided exactly as a send decides it. The source of truth for \"can I reply free-form now\"."},"bot_active":{"type":"boolean"},"last_message":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":["string","null"]},"type":{"type":"string","description":"TEXT, IMAGE, VIDEO, AUDIO, DOCUMENT, STICKER, LOCATION, TEMPLATE, INTERACTIVE, ORDER, CONTACTS, SYSTEM"},"direction":{"type":"string","enum":["inbound","outbound","system"]},"status":{"type":"string","description":"received (inbound) | pending | sent | delivered | read | failed | system"},"text":{"description":"Message text, or the caption for media. Media files/URLs are never included.","type":["string","null"]},"text_truncated":{"type":"boolean"},"has_media":{"type":"boolean"},"from":{"anyOf":[{"type":"object","properties":{"staff_id":{"type":["string","null"]},"staff_name":{"type":["string","null"]},"bot":{"type":"boolean"}},"required":["staff_id","staff_name","bot"],"additionalProperties":false},{"type":"null"}],"description":"Who sent an outbound message (staff or bot); null for inbound."},"reply_to_id":{"type":["string","null"]},"error":{"type":["string","null"]},"created_at":{"type":["string","null"]}},"required":["id","conversation_id","type","direction","status","text","text_truncated","has_media","from","reply_to_id","error","created_at"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","state","contact","channel","assignee","team_id","assigned_at","tags","starred","unread_count","reply_status","sla","reminder_at","whatsapp_window_expires_at","window","bot_active","last_message","created_at","updated_at"],"additionalProperties":false},"episode_title":{"type":["string","null"]},"permissions":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"boolean"},"description":"What the connected staff member may do on this conversation (assign, close, …)."},"last_messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":["string","null"]},"type":{"type":"string","description":"TEXT, IMAGE, VIDEO, AUDIO, DOCUMENT, STICKER, LOCATION, TEMPLATE, INTERACTIVE, ORDER, CONTACTS, SYSTEM"},"direction":{"type":"string","enum":["inbound","outbound","system"]},"status":{"type":"string","description":"received (inbound) | pending | sent | delivered | read | failed | system"},"text":{"description":"Message text, or the caption for media. Media files/URLs are never included.","type":["string","null"]},"text_truncated":{"type":"boolean"},"has_media":{"type":"boolean"},"from":{"anyOf":[{"type":"object","properties":{"staff_id":{"type":["string","null"]},"staff_name":{"type":["string","null"]},"bot":{"type":"boolean"}},"required":["staff_id","staff_name","bot"],"additionalProperties":false},{"type":"null"}],"description":"Who sent an outbound message (staff or bot); null for inbound."},"reply_to_id":{"type":["string","null"]},"error":{"type":["string","null"]},"created_at":{"type":["string","null"]}},"required":["id","conversation_id","type","direction","status","text","text_truncated","has_media","from","reply_to_id","error","created_at"],"additionalProperties":false},"description":"Newest first."}},"required":["conversation","episode_title","permissions","last_messages"]},"examples":{"one":{"summary":"Read a conversation","value":{"conversation":{"id":"77410","state":"open","contact":{"id":"48213","name":"Jane Doe","phone":"+15555550123","dnd_enabled":false,"groups":[]},"channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"assignee":null,"team_id":null,"tags":[{"id":"4","name":"new-lead"}],"unread_count":2,"reply_status":"incoming_no_reply","whatsapp_window_expires_at":"2026-09-25T09:12:00Z","window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null,"reason":null},"last_message":{"id":"5501234","type":"TEXT","direction":"inbound","status":"received","text":"Hi, is the blue one in stock?","created_at":"2026-09-24T09:12:00Z","conversation_id":null,"text_truncated":false,"has_media":false,"from":null,"reply_to_id":null,"error":null},"created_at":"2026-09-24T09:11:40Z","updated_at":"2026-09-24T09:12:00Z","assigned_at":null,"starred":false,"sla":null,"reminder_at":null,"bot_active":false},"last_messages":[{"id":"5501234","type":"TEXT","direction":"inbound","status":"received","text":"Hi, is the blue one in stock?","created_at":"2026-09-24T09:12:00Z","conversation_id":null,"text_truncated":false,"has_media":false,"from":null,"reply_to_id":null,"error":null}],"episode_title":null,"permissions":{}}},"window":{"summary":"Check if the 24-hour reply window (customer service window, WhatsApp session) is open before replying","value":{"conversation":{"id":"77410","state":"open","contact":{"id":"48213","name":"Jane Doe","phone":"+15555550123","dnd_enabled":false,"groups":[]},"channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"assignee":null,"team_id":null,"tags":[{"id":"4","name":"new-lead"}],"unread_count":2,"reply_status":"incoming_no_reply","whatsapp_window_expires_at":"2026-09-25T09:12:00Z","window":{"applies":true,"open":false,"kind":"service","closes_at":null,"closed_at":"2026-09-25T09:12:00.000Z","reason":"expired"},"last_message":{"id":"5501234","type":"TEXT","direction":"inbound","status":"received","text":"Hi, is the blue one in stock?","created_at":"2026-09-24T09:12:00Z","conversation_id":null,"text_truncated":false,"has_media":false,"from":null,"reply_to_id":null,"error":null},"created_at":"2026-09-24T09:11:40Z","updated_at":"2026-09-24T09:12:00Z","assigned_at":null,"starred":false,"sla":null,"reminder_at":null,"bot_active":false},"last_messages":[],"episode_title":null,"permissions":{}}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id, or your key cannot see it.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id, or your key cannot see it.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id, or your key cannot see it.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_get_conversation","x-platform-ops-path":"/ops/inbox_get_conversation","x-platform-group":"inbox","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id, or your key cannot see it."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"one","summary":"Read a conversation","path":{"conversation_id":"77410"},"query":{},"response":{"status":200,"body":{"conversation":{"id":"77410","state":"open","contact":{"id":"48213","name":"Jane Doe","phone":"+15555550123","dnd_enabled":false,"groups":[]},"channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"assignee":null,"team_id":null,"tags":[{"id":"4","name":"new-lead"}],"unread_count":2,"reply_status":"incoming_no_reply","whatsapp_window_expires_at":"2026-09-25T09:12:00Z","window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null,"reason":null},"last_message":{"id":"5501234","type":"TEXT","direction":"inbound","status":"received","text":"Hi, is the blue one in stock?","created_at":"2026-09-24T09:12:00Z","conversation_id":null,"text_truncated":false,"has_media":false,"from":null,"reply_to_id":null,"error":null},"created_at":"2026-09-24T09:11:40Z","updated_at":"2026-09-24T09:12:00Z","assigned_at":null,"starred":false,"sla":null,"reminder_at":null,"bot_active":false},"last_messages":[{"id":"5501234","type":"TEXT","direction":"inbound","status":"received","text":"Hi, is the blue one in stock?","created_at":"2026-09-24T09:12:00Z","conversation_id":null,"text_truncated":false,"has_media":false,"from":null,"reply_to_id":null,"error":null}],"episode_title":null,"permissions":{}}}},{"name":"window","summary":"Check if the 24-hour reply window (customer service window, WhatsApp session) is open before replying","path":{"conversation_id":"77410"},"query":{"last_messages":0},"response":{"status":200,"body":{"conversation":{"id":"77410","state":"open","contact":{"id":"48213","name":"Jane Doe","phone":"+15555550123","dnd_enabled":false,"groups":[]},"channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"assignee":null,"team_id":null,"tags":[{"id":"4","name":"new-lead"}],"unread_count":2,"reply_status":"incoming_no_reply","whatsapp_window_expires_at":"2026-09-25T09:12:00Z","window":{"applies":true,"open":false,"kind":"service","closes_at":null,"closed_at":"2026-09-25T09:12:00.000Z","reason":"expired"},"last_message":{"id":"5501234","type":"TEXT","direction":"inbound","status":"received","text":"Hi, is the blue one in stock?","created_at":"2026-09-24T09:12:00Z","conversation_id":null,"text_truncated":false,"has_media":false,"from":null,"reply_to_id":null,"error":null},"created_at":"2026-09-24T09:11:40Z","updated_at":"2026-09-24T09:12:00Z","assigned_at":null,"starred":false,"sla":null,"reminder_at":null,"bot_active":false},"last_messages":[],"episode_title":null,"permissions":{}}}}]}},"/conversations/{conversation_id}/messages":{"get":{"operationId":"listConversationMessages","summary":"List messages of a conversation","description":"Returns the messages of one conversation, newest first (or oldest first with `order=oldest_first`). Each message has its type, direction (`inbound` from the customer, `outbound` from your team, a bot or the API, `system` for notes like assignments), delivery status and its text or caption. Media files and their links are never included. Reading does not mark anything as read.\n\nPages hold 1–100 messages (`limit`, default 25). Pass `next_cursor` as `cursor` to get the next page; it is null on the last page. With the `types`, `direction` or `status` filters a page may hold fewer than `limit` messages while `next_cursor` is still set: keep paging until it is null.","tags":["messages"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"The conversation id."},"x-platform-picker":"conversations"},{"name":"order","in":"query","required":false,"description":"`newest_first` (default) or `oldest_first`.","schema":{"default":"newest_first","description":"`newest_first` (default) or `oldest_first`.","type":"string","enum":["newest_first","oldest_first"]}},{"name":"search","in":"query","required":false,"description":"Only messages containing this text.","schema":{"description":"Only messages containing this text.","type":"string","minLength":1,"maxLength":200}},{"name":"types","in":"query","required":false,"description":"Only these message types. Repeat the parameter for several.","schema":{"description":"Only these message types. Repeat the parameter for several.","minItems":1,"type":"array","items":{"type":"string","enum":["TEXT","IMAGE","VIDEO","AUDIO","DOCUMENT","STICKER","LOCATION","TEMPLATE","INTERACTIVE","ORDER","CONTACTS","SYSTEM"]}},"style":"form","explode":true},{"name":"direction","in":"query","required":false,"description":"`inbound` = from the customer; `outbound` = from your team, a bot or the API; `system` = assignment and close notes.","schema":{"description":"`inbound` = from the customer; `outbound` = from your team, a bot or the API; `system` = assignment and close notes.","type":"string","enum":["inbound","outbound","system"]}},{"name":"status","in":"query","required":false,"description":"Only messages with this delivery status.","schema":{"description":"Only messages with this delivery status.","type":"string","enum":["received","pending","sent","delivered","read","failed"]}},{"name":"failed_only","in":"query","required":false,"description":"Only messages that failed to deliver.","schema":{"description":"Only messages that failed to deliver.","type":"boolean"}},{"name":"max_text_chars","in":"query","required":false,"description":"Cut each message text after this many characters (50–4000, default 1000); `text_truncated` tells.","schema":{"default":1000,"description":"Cut each message text after this many characters (50–4000, default 1000); `text_truncated` tells.","type":"integer","minimum":50,"maximum":4000}},{"name":"limit","in":"query","required":false,"description":"How many messages per page (1–100, default 25).","schema":{"default":25,"description":"How many messages per page (1–100, default 25).","type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of messages.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":["string","null"]},"type":{"type":"string","description":"TEXT, IMAGE, VIDEO, AUDIO, DOCUMENT, STICKER, LOCATION, TEMPLATE, INTERACTIVE, ORDER, CONTACTS, SYSTEM"},"direction":{"type":"string","enum":["inbound","outbound","system"]},"status":{"type":"string","description":"received (inbound) | pending | sent | delivered | read | failed | system"},"text":{"description":"Message text, or the caption for media. Media files/URLs are never included.","type":["string","null"]},"text_truncated":{"type":"boolean"},"has_media":{"type":"boolean"},"from":{"anyOf":[{"type":"object","properties":{"staff_id":{"type":["string","null"]},"staff_name":{"type":["string","null"]},"bot":{"type":"boolean"}},"required":["staff_id","staff_name","bot"],"additionalProperties":false},{"type":"null"}],"description":"Who sent an outbound message (staff or bot); null for inbound."},"reply_to_id":{"type":["string","null"]},"error":{"type":["string","null"]},"created_at":{"type":["string","null"]}},"required":["id","conversation_id","type","direction","status","text","text_truncated","has_media","from","reply_to_id","error","created_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as \"cursor\" to get the next page; null when there are no more results.","type":["string","null"]}},"required":["data","next_cursor"]},"examples":{"latest":{"summary":"The latest messages","value":{"data":[{"id":"5501235","conversation_id":"77410","type":"TEXT","direction":"outbound","status":"delivered","text":"Yes! It ships today.","text_truncated":false,"has_media":false,"from":{"staff_id":"1203","staff_name":"Priya Nair","bot":false},"reply_to_id":"5501234","error":null,"created_at":"2026-09-24T09:14:00Z"},{"id":"5501234","conversation_id":"77410","type":"TEXT","direction":"inbound","status":"received","text":"Hi, is the blue one in stock?","text_truncated":false,"has_media":false,"from":null,"reply_to_id":null,"error":null,"created_at":"2026-09-24T09:12:00Z"}],"next_cursor":"eyJ2IjoxLCJwIjp7ImMiOiJNZyJ9fQ.q1f0bm9ZS2dLQnVQ"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id, or your key cannot see it.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id, or your key cannot see it.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id, or your key cannot see it.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_list_messages","x-platform-ops-path":"/ops/inbox_list_messages","x-platform-group":"messages","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id, or your key cannot see it."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"latest","summary":"The latest messages","path":{"conversation_id":"77410"},"query":{"limit":2},"response":{"status":200,"body":{"data":[{"id":"5501235","conversation_id":"77410","type":"TEXT","direction":"outbound","status":"delivered","text":"Yes! It ships today.","text_truncated":false,"has_media":false,"from":{"staff_id":"1203","staff_name":"Priya Nair","bot":false},"reply_to_id":"5501234","error":null,"created_at":"2026-09-24T09:14:00Z"},{"id":"5501234","conversation_id":"77410","type":"TEXT","direction":"inbound","status":"received","text":"Hi, is the blue one in stock?","text_truncated":false,"has_media":false,"from":null,"reply_to_id":null,"error":null,"created_at":"2026-09-24T09:12:00Z"}],"next_cursor":"eyJ2IjoxLCJwIjp7ImMiOiJNZyJ9fQ.q1f0bm9ZS2dLQnVQ"}}}]},"post":{"operationId":"sendConversationMessage","summary":"Send a message in a conversation","description":"Replies in a conversation you already have, on the conversation's own channel (WhatsApp, Instagram, Messenger, TikTok or web chat): text, media by public https link, a location, buttons, a list, a link button or a reaction. **The customer receives it and it cannot be undone.** To reach a customer by contact id or WhatsApp number instead, use **Send a message** (`POST /v1/messages`). For a line only your team sees, use **Add a system message**.\n\nFree-form messages need an open reply window where the channel has one (on WhatsApp, 24 hours after the customer's last message). When it is closed the answer is `409` with `reason: window_closed`: send an approved template with `POST /v1/messages/template` instead. Some types do not exist on some channels (no stickers on Instagram, no location on TikTok): `400` with `reason: unsupported_on_channel`. Text is at most 4096 characters.\n\nThe key's staff member must be allowed to reply here (the conversation is open and theirs, or they lead its team or manage the inbox). Customer messages count against the workspace send limits. Try it with `?dry_run=true`: every check runs (conversation, permission, window, channel) and nothing is sent.","tags":["messages"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"description":"The conversation id.","type":"string","pattern":"^\\d{1,19}$"},"x-platform-picker":"conversations"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["text","image","video","audio","document","sticker","location","interactive","reaction","system"],"description":"What to send: `text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `interactive` or `reaction`. Send exactly the one matching block. (`system` is an older alias of **Add a system message**.)"},"text":{"description":"type `text`: the message (1–4096 characters).","type":"string","minLength":1,"maxLength":4096},"reply_to_message_id":{"description":"Quote this message of the conversation (a message id from its message list).","type":"string","pattern":"^\\d{1,19}$"},"media":{"description":"type `image`, `video`, `audio`, `document` or `sticker`: `url`, a public https link to the file, with an optional `caption` (not for audio or stickers) and a `filename` for documents. The platform downloads the link when you send (it must answer directly, without a login or a redirect, within 60 seconds) and checks the file by its content: image JPEG or PNG up to 5 MB (WebP, GIF, HEIC and other images are converted), video MP4 or 3GP up to 16 MB, audio MP3, AAC, AMR, OGG or M4A up to 16 MB (other audio is converted), document PDF, Word, Excel or text up to 100 MB, sticker WebP up to 500 KB. The link must name its host on the default port (no IP address, port, user name, backslash or control character); a host that is private or internal, or that does not resolve, is refused (`reason: url_refused`, `private_address` or `dns_failed`). To send a file from your own system without hosting it, use **Send a file in a conversation** (`POST /v1/conversations/{conversation_id}/files`).","type":"object","properties":{"url":{"type":"string","maxLength":2000,"description":"Public https URL of the file (the platform downloads it)."},"caption":{"description":"Caption (image, video, document).","type":"string","maxLength":1024},"filename":{"description":"document: file name shown.","type":"string","maxLength":200}},"required":["url"]},"location":{"description":"type `location`: latitude, longitude, and an optional name and address.","type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude."},"name":{"description":"Place name.","type":"string","maxLength":255},"address":{"description":"Address.","type":"string","maxLength":255}},"required":["latitude","longitude"]},"interactive":{"description":"type `interactive`: `kind` `buttons` (1–3 quick replies), `list` (a menu of up to 10 rows) or `cta_url` (one link button).","type":"object","properties":{"kind":{"type":"string","enum":["buttons","list","cta_url"],"description":"buttons (1–3 quick replies), list (a menu), cta_url (one link button)."},"body":{"type":"string","minLength":1,"maxLength":1024,"description":"Message text (≤ 1024)."},"header":{"description":"Header text (≤ 60).","type":"string","maxLength":60},"footer":{"description":"Footer text (≤ 60).","type":"string","maxLength":60},"buttons":{"description":"kind buttons: 1–3 buttons, unique ids and titles.","minItems":1,"maxItems":3,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256,"description":"Reply id you get back when tapped."},"title":{"type":"string","minLength":1,"maxLength":20,"description":"Button text (≤ 20)."}},"required":["id","title"]}},"list_button":{"description":"kind list: the text of the button that opens the menu (≤ 20).","type":"string","minLength":1,"maxLength":20},"sections":{"description":"kind list: 1–10 sections, 10 rows in total at most.","minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"title":{"description":"Section title (≤ 24; needed with several sections).","type":"string","maxLength":24},"rows":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"Row id you get back."},"title":{"type":"string","minLength":1,"maxLength":24,"description":"Row title (≤ 24)."},"description":{"description":"Row description (≤ 72).","type":"string","maxLength":72}},"required":["id","title"]},"description":"Rows."}},"required":["rows"]}},"url":{"description":"kind cta_url: https link.","type":"string","maxLength":2000,"format":"uri"},"url_text":{"description":"kind cta_url: button text (≤ 20).","type":"string","minLength":1,"maxLength":20}},"required":["kind","body"]},"reaction":{"description":"type `reaction`: the message id to react to and one emoji (`\"\"` removes the reaction).","type":"object","properties":{"message_id":{"type":"string","pattern":"^\\d{1,19}$","description":"Message to react to (`GET /v1/conversations/{conversation_id}/messages` id)."},"emoji":{"type":"string","maxLength":16,"description":"One emoji; \"\" removes the reaction."}},"required":["message_id","emoji"]},"system":{"description":"Deprecated: use **Add a system message** (`POST /v1/conversations/{conversation_id}/system-messages`), which takes the same fields. Still accepted with `type: system`.","type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":4096,"description":"The line shown in the thread to staff (plain text, ≤ 4096)."},"priority":{"description":"High priority: moves the conversation up and notifies its assignee, a manager and the team leads (in-app + push).","type":"boolean"},"system_type":{"description":"What kind of event the line records, e.g. ORDER_UPDATE, PAYMENT_RECEIVED, SHIPPING_UPDATE, CRM_SYNC (upper-cased; default NOTIFICATION). Reserved for the platform: MENTION, REMINDER, REMINDER_SET, REMINDER_ACKNOWLEDGED, REMINDER_DELETED, REMINDER_UPDATED, SLA_BREACH, CALL_EVENT, CLIENT_ACTION.","type":"string","maxLength":100,"pattern":"^[A-Za-z][A-Za-z0-9_]*$"},"meta":{"description":"Structured data kept with the line (JSON object, ≤ 4096 bytes, nesting ≤ 3 levels, ≤ 50 keys per object) for integrations that read the thread later. Shown to staff as plain text at most; `source` (text ≤ 200 characters, or a number) appears in the priority notification. Reserved keys: mentionStaffs, acknowledged, reminder_id, created_by_staff_id, idempotency_key.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["text"],"deprecated":true}},"required":["type"],"additionalProperties":false},"examples":{"reply":{"summary":"Reply to a customer","value":{"type":"text","text":"Yes! The blue one is in stock and ships today.","reply_to_message_id":"5501234"}},"buttons":{"summary":"Ask with quick-reply buttons","value":{"type":"interactive","interactive":{"kind":"buttons","body":"Would you like us to hold one for you?","buttons":[{"id":"hold_yes","title":"Yes, please"},{"id":"hold_no","title":"No, thanks"}]}}}}}}},"responses":{"202":{"description":"Accepted for delivery (or the dry-run check). Delivery and read receipts show as the message's `status` in the message list.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"message_id":{"type":["string","null"]},"status":{"type":"string","description":"queued (accepted for delivery), created (system line) or dry_run."},"type":{"type":"string"},"conversation_id":{"type":"string","description":"The conversation it went into (resolved from contactId / phone when those were given)."},"contact_id":{"description":"The customer it went to.","type":["string","null"]},"channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"type":{"type":"string"}},"required":["id","name","type"],"additionalProperties":false},"window":{"type":"object","properties":{"applies":{"type":"boolean","description":"false for channels without a window (web chat, custom) and for system messages."},"open":{"description":"null when the window does not apply.","type":["boolean","null"]},"kind":{"description":"service (24 h), free_entry (72 h after an ad), standard, tiktok (48 h), web.","type":["string","null"]},"closes_at":{"description":"Open window: when it closes.","type":["string","null"]},"closed_at":{"description":"Closed window: when it closed (null = the customer never wrote on this channel, or unknown).","type":["string","null"]}},"required":["applies","open","kind","closes_at","closed_at"],"additionalProperties":false},"visible_to_customer":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["message_id","status","type","conversation_id","contact_id","channel","window","visible_to_customer"]},"examples":{"reply":{"summary":"Reply to a customer","value":{"message_id":"5501236","status":"queued","type":"text","conversation_id":"77410","contact_id":"48213","channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null},"visible_to_customer":true}},"buttons":{"summary":"Ask with quick-reply buttons","value":{"message_id":"5501237","status":"queued","type":"interactive","conversation_id":"77410","contact_id":"48213","channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null},"visible_to_customer":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The type's block is missing or another one was sent, a media link is not public https, or the channel cannot carry this type (`reason: unsupported_on_channel`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The type's block is missing or another one was sent, a media link is not public https, or the channel cannot carry this type (`reason: unsupported_on_channel`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The type's block is missing or another one was sent, a media link is not public https, or the channel cannot carry this type (`reason: unsupported_on_channel`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The key's staff member may not reply here: the conversation is closed, or assigned to someone else (`reason: cannot_send_here`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The key's staff member may not reply here: the conversation is closed, or assigned to someone else (`reason: cannot_send_here`).","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The key's staff member may not reply here: the conversation is closed, or assigned to someone else (`reason: cannot_send_here`).","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id, or your key cannot see it.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id, or your key cannot see it.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id, or your key cannot see it.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: The customer's reply window is closed (`reason: window_closed`): send a template instead. Or the channel refused the message (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"The customer's reply window is closed (`reason: window_closed`): send a template instead. Or the channel refused the message (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"The customer's reply window is closed (`reason: window_closed`): send a template instead. Or the channel refused the message (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day).","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day).","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_send_message","x-platform-ops-path":"/ops/inbox_send_message","x-platform-group":"messages","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-send-caps":{"per_hour":20,"per_day":100,"per_recipient_per_day":3},"x-platform-idempotency":"required","x-platform-dry-run":"native","x-platform-destructive-verb":null,"x-platform-undo":"Cannot be undone: the customer receives the message.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The type's block is missing or another one was sent, a media link is not public https, or the channel cannot carry this type (`reason: unsupported_on_channel`). Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The key's staff member may not reply here: the conversation is closed, or assigned to someone else (`reason: cannot_send_here`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id, or your key cannot see it."},{"code":"conflict","status":409,"when":"The customer's reply window is closed (`reason: window_closed`): send a template instead. Or the channel refused the message (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day)."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"reply","summary":"Reply to a customer","path":{"conversation_id":"77410"},"query":{},"body":{"type":"text","text":"Yes! The blue one is in stock and ships today.","reply_to_message_id":"5501234"},"response":{"status":202,"body":{"message_id":"5501236","status":"queued","type":"text","conversation_id":"77410","contact_id":"48213","channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null},"visible_to_customer":true}}},{"name":"buttons","summary":"Ask with quick-reply buttons","path":{"conversation_id":"77410"},"query":{},"body":{"type":"interactive","interactive":{"kind":"buttons","body":"Would you like us to hold one for you?","buttons":[{"id":"hold_yes","title":"Yes, please"},{"id":"hold_no","title":"No, thanks"}]}},"response":{"status":202,"body":{"message_id":"5501237","status":"queued","type":"interactive","conversation_id":"77410","contact_id":"48213","channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null},"visible_to_customer":true}}}]}},"/conversations/counts":{"get":{"operationId":"getConversationCounts","summary":"Count conversations","description":"Returns the inbox tab counts your key's staff member sees — all, unassigned, open, active (the customer wrote in the last 24 hours), pending reply, awaiting response, starred, closed and SLA breached — plus how many conversations have unread messages.\n\nCounts stop at 100: a key listed in `capped` means \"100 or more\". `counts` is null when per-tab counts are not enabled for the workspace (then `note` says so and only `unread` is set).","tags":["inbox"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"unread_state","in":"query","required":false,"description":"Count unread messages only in open or only in closed conversations.","schema":{"description":"Count unread messages only in open or only in closed conversations.","type":"string","enum":["open","closed"]}},{"name":"unread_mine","in":"query","required":false,"description":"Count unread messages only in conversations assigned to the key's staff member.","schema":{"description":"Count unread messages only in conversations assigned to the key's staff member.","type":"boolean"}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The counts.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"counts":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},{"type":"null"}],"description":"Per-tab counts; null when counts are not enabled for this workspace."},"capped":{"type":"array","items":{"type":"string"},"description":"Keys whose value hit the 100 cap (meaning \"100 or more\")."},"unread":{"description":"Conversations with unread messages (capped at 100).","type":["number","null"]},"note":{"type":"string"}},"required":["counts","capped","unread"]},"examples":{"tabs":{"summary":"Inbox tab counts for a dashboard","value":{"counts":{"all":100,"unassigned":4,"open":12,"active":7,"pending_reply":3,"awaiting_response":2,"starred":0,"closed":100,"breached":1},"capped":["all","closed"],"unread":9}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_counts","x-platform-ops-path":"/ops/inbox_counts","x-platform-group":"inbox","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"tabs","summary":"Inbox tab counts for a dashboard","path":{},"query":{},"response":{"status":200,"body":{"counts":{"all":100,"unassigned":4,"open":12,"active":7,"pending_reply":3,"awaiting_response":2,"starred":0,"closed":100,"breached":1},"capped":["all","closed"],"unread":9}}}]}},"/conversations/{conversation_id}/assignment":{"put":{"operationId":"assignConversation","summary":"Assign a conversation","description":"Assigns a conversation to a staff member or a team — give exactly one of `staff_id` or `team_id`. It reassigns if someone already has it, unless you set `only_if_unassigned`.\n\nThe assignee must have access to the channel.","tags":["inbox"],"security":[{"api_key":["inbox:write"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"The conversation id."},"x-platform-picker":"conversations"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"staff_id":{"description":"Assign to this staff member.","type":"string","pattern":"^\\d{1,19}$"},"team_id":{"description":"Assign to this team (clears the staff assignee).","type":"string","pattern":"^\\d{1,19}$"},"only_if_unassigned":{"default":false,"description":"Refuse instead of reassigning.","type":"boolean"}},"additionalProperties":false},"examples":{"staff":{"summary":"Give a new lead to a sales rep","value":{"staff_id":"1203","only_if_unassigned":true}}}}}},"responses":{"200":{"description":"The new assignment.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversation":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":["string","null"]},"assignee_staff_id":{"type":["string","null"]},"team_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["id","state","assignee_staff_id","team_id","tags"],"additionalProperties":false},"assigned_to":{"type":"string"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["conversation","assigned_to"]},"examples":{"staff":{"summary":"Give a new lead to a sales rep","value":{"conversation":{"id":"77410","state":"open","assignee_staff_id":"1203","team_id":null,"tags":[{"id":"4","name":"new-lead"}]},"assigned_to":"Priya Nair"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The assignee has no access to this channel or is disabled. `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The assignee has no access to this channel or is disabled.","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The assignee has no access to this channel or is disabled.","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Already assigned and `only_if_unassigned` is true. Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Already assigned and `only_if_unassigned` is true. Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Already assigned and `only_if_unassigned` is true. Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_assign_conversation","x-platform-ops-path":"/ops/inbox_assign_conversation","x-platform-group":"inbox","x-platform-scope":"inbox:write","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Assign it back, or use **Unassign a conversation**.","x-platform-events":["conversation.assigned/1"],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The assignee has no access to this channel or is disabled."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id."},{"code":"conflict","status":409,"when":"Already assigned and `only_if_unassigned` is true. Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"staff","summary":"Give a new lead to a sales rep","path":{"conversation_id":"77410"},"query":{},"body":{"staff_id":"1203","only_if_unassigned":true},"response":{"status":200,"body":{"conversation":{"id":"77410","state":"open","assignee_staff_id":"1203","team_id":null,"tags":[{"id":"4","name":"new-lead"}]},"assigned_to":"Priya Nair"}}}]},"delete":{"operationId":"unassignConversation","summary":"Unassign a conversation","description":"Removes the staff assignee, so the conversation goes back to the unassigned queue. It stays open.","tags":["inbox"],"security":[{"api_key":["inbox:write"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"The conversation id."},"x-platform-picker":"conversations"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"The updated state.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversation":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":["string","null"]},"assignee_staff_id":{"type":["string","null"]},"team_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["id","state","assignee_staff_id","team_id","tags"],"additionalProperties":false},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["conversation"]},"examples":{"unassign":{"summary":"Back to the queue","value":{"conversation":{"id":"77410","state":"open","assignee_staff_id":null,"team_id":null,"tags":[]}}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_unassign_conversation","x-platform-ops-path":"/ops/inbox_unassign_conversation","x-platform-group":"inbox","x-platform-scope":"inbox:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Assign it again.","x-platform-events":["conversation.unassigned/1"],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"unassign","summary":"Back to the queue","path":{"conversation_id":"77410"},"query":{},"response":{"status":200,"body":{"conversation":{"id":"77410","state":"open","assignee_staff_id":null,"team_id":null,"tags":[]}}}}]}},"/conversations/{conversation_id}/close":{"post":{"operationId":"closeConversation","summary":"Close a conversation","description":"Closes a conversation with a closing reason: it ends the current episode, stops its SLA clock and fires `conversation.closed` automations and webhooks. Optionally adds an internal note first.\n\nSend `Api-Confirm: close`. Closing one that is already closed changes nothing (`changed: false`). A new message from the customer reopens it.","tags":["inbox"],"security":[{"api_key":["inbox:write"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"The conversation id."},"x-platform-picker":"conversations"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/Api-Confirm"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"closed_reason_id":{"type":"string","pattern":"^\\d{1,19}$","description":"The id of one of the workspace's closing reasons (set up in the inbox settings)."},"note":{"description":"An internal note to add before closing (never shown to the customer).","type":"string","minLength":1,"maxLength":5000}},"required":["closed_reason_id"],"additionalProperties":false},"examples":{"resolved":{"summary":"Close a resolved conversation","value":{"closed_reason_id":"3","note":"Order shipped; the customer confirmed."}}}}}},"responses":{"200":{"description":"The conversation's new state.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversation":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":["string","null"]},"assignee_staff_id":{"type":["string","null"]},"team_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["id","state","assignee_staff_id","team_id","tags"],"additionalProperties":false},"changed":{"type":"boolean"},"note_id":{"type":["string","null"]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["conversation","changed","note_id"]},"examples":{"resolved":{"summary":"Close a resolved conversation","value":{"conversation":{"id":"77410","state":"closed","assignee_staff_id":"1203","team_id":null,"tags":[{"id":"4","name":"new-lead"}]},"changed":true,"note_id":"90332"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. `closed_reason_id` is missing or not a closing reason of this workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. `closed_reason_id` is missing or not a closing reason of this workspace.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. `closed_reason_id` is missing or not a closing reason of this workspace.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"428":{"description":"`confirm_required`: Send the header `Api-Confirm: close` to confirm. Not needed with `dry_run=true`.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"confirm_required":{"summary":"Send the header `Api-Confirm: close` to confirm. Not needed with `dry_run=true`.","value":{"type":"https://dev.wa-api.cloud/errors/confirm_required","title":"Confirmation header missing","status":428,"detail":"Send the header `Api-Confirm: close` to confirm. Not needed with `dry_run=true`.","code":"confirm_required","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_close_conversation","x-platform-ops-path":"/ops/inbox_close_conversation","x-platform-group":"inbox","x-platform-scope":"inbox:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":"close","x-platform-undo":"Reopen it with **Reopen a conversation** (a new episode starts; the automations that ran on close are not undone).","x-platform-events":["conversation.closed/1"],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. `closed_reason_id` is missing or not a closing reason of this workspace."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"confirm_required","status":428,"when":"Send the header `Api-Confirm: close` to confirm. Not needed with `dry_run=true`."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"resolved","summary":"Close a resolved conversation","path":{"conversation_id":"77410"},"query":{},"body":{"closed_reason_id":"3","note":"Order shipped; the customer confirmed."},"response":{"status":200,"body":{"conversation":{"id":"77410","state":"closed","assignee_staff_id":"1203","team_id":null,"tags":[{"id":"4","name":"new-lead"}]},"changed":true,"note_id":"90332"}}}]}},"/conversations/{conversation_id}/reopen":{"post":{"operationId":"reopenConversation","summary":"Reopen a conversation","description":"Reopens a closed conversation and starts a new episode, optionally with a title. SLA clocks follow the workspace's rules. Reopening one that is already open changes nothing (`changed: false`).","tags":["inbox"],"security":[{"api_key":["inbox:write"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"The conversation id."},"x-platform-picker":"conversations"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"description":"A title for the new episode, e.g. \"Refund follow-up\" (up to 120 characters).","type":"string","minLength":1,"maxLength":120}},"additionalProperties":false},"examples":{"reopen":{"summary":"Pick a closed conversation up again","value":{"title":"Refund follow-up"}}}}}},"responses":{"200":{"description":"The conversation's new state.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversation":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":["string","null"]},"assignee_staff_id":{"type":["string","null"]},"team_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["id","state","assignee_staff_id","team_id","tags"],"additionalProperties":false},"changed":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["conversation","changed"]},"examples":{"reopen":{"summary":"Pick a closed conversation up again","value":{"conversation":{"id":"77410","state":"open","assignee_staff_id":null,"team_id":null,"tags":[]},"changed":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_reopen_conversation","x-platform-ops-path":"/ops/inbox_reopen_conversation","x-platform-group":"inbox","x-platform-scope":"inbox:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Close it again.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"reopen","summary":"Pick a closed conversation up again","path":{"conversation_id":"77410"},"query":{},"body":{"title":"Refund follow-up"},"response":{"status":200,"body":{"conversation":{"id":"77410","state":"open","assignee_staff_id":null,"team_id":null,"tags":[]},"changed":true}}}]}},"/conversations/{conversation_id}/notes":{"post":{"operationId":"addConversationNote","summary":"Add an internal note","description":"Adds an internal note to a conversation for your team — a handover, a ticket link, a summary. **Notes are never sent to the customer.**\n\nMention colleagues with `mention_staff_ids` and/or `mention_emails` (up to 20 people; duplicates are ignored, emails match case-insensitively). Each person mentioned gets an in-app and push notification, and a `conversation.mention.created` event is sent for each. The note is then posted as a mention line in the conversation (at most 2000 characters), `kind` is `mention` and `mentioned` lists who was notified. Write `{{staff_id}}` in the text to place a mention inline; otherwise the mentioned people are listed before the text. Every person is checked first: if any id or email is not an active staff member of your workspace you can mention, the answer is `400` with `reason: unknown_staff`, `errors[]` points at each one, and nothing is added. You may mention yourself.\n\nA note with mentions needs an `Idempotency-Key` header (a plain note does not): a retry then never notifies anyone twice. Try it with `?dry_run=true` first: every check runs and the answer lists exactly who would be notified (`mentioned`), with `note_id: null`; nothing is written and nobody is notified.","tags":["inbox"],"security":[{"api_key":["inbox:write"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"The conversation id."},"x-platform-picker":"conversations"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":5000,"description":"The note (staff only): up to 5000 characters, or 2000 with mentions. `{{staff_id}}` places a mentioned person inline."},"mention_staff_ids":{"description":"Mention these staff members by id (up to 20 people in total). Each is notified.","minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^\\d{1,19}$","description":"Staff id."}},"mention_emails":{"description":"Mention staff members by their login email (case-insensitive; up to 20 people in total).","minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}}},"required":["text"],"additionalProperties":false},"examples":{"ticket":{"summary":"Link a helpdesk ticket","value":{"text":"Ticket #4411 opened in the helpdesk: https://help.example.com/tickets/4411"}},"mention":{"summary":"Ask a colleague to take a look","value":{"text":"{{1203}} can you approve the refund for this order?","mention_staff_ids":["1203"],"mention_emails":["finance@example.com"]}}}}}},"responses":{"201":{"description":"The note was added.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"note_id":{"description":"The note id; with mentions, the id of the mention line in the thread. null in a dry run.","type":["string","null"]},"conversation_id":{"type":"string"},"visible_to_customer":{"type":"boolean","const":false},"kind":{"type":"string","enum":["note","mention"],"description":"note = a plain internal note; mention = posted as a mention line that notified `mentioned`."},"mentioned":{"type":"array","items":{"type":"object","properties":{"staff_id":{"type":"string"},"name":{"type":["string","null"]}},"required":["staff_id","name"],"additionalProperties":false},"description":"Who was mentioned and notified (empty for a plain note); in a dry run, who would be."},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["note_id","conversation_id","visible_to_customer","kind","mentioned"]},"examples":{"ticket":{"summary":"Link a helpdesk ticket","value":{"note_id":"90331","conversation_id":"77410","visible_to_customer":false,"kind":"note","mentioned":[]}},"mention":{"summary":"Ask a colleague to take a look","value":{"note_id":"5501240","conversation_id":"77410","visible_to_customer":false,"kind":"mention","mentioned":[{"staff_id":"1203","name":"Priya Nair"},{"staff_id":"1207","name":"Finance Team"}]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. A mentioned id or email is not an active staff member of your workspace (`reason: unknown_staff`), more than 20 people, a note with mentions is longer than 2000 characters, or has no `Idempotency-Key` header.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. A mentioned id or email is not an active staff member of your workspace (`reason: unknown_staff`), more than 20 people, a note with mentions is longer than 2000 characters, or has no `Idempotency-Key` header.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. A mentioned id or email is not an active staff member of your workspace (`reason: unknown_staff`), more than 20 people, a note with mentions is longer than 2000 characters, or has no `Idempotency-Key` header.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_add_note","x-platform-ops-path":"/ops/inbox_add_note","x-platform-group":"inbox","x-platform-scope":"inbox:write","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"native","x-platform-destructive-verb":null,"x-platform-undo":"Notes can be deleted in the inbox. Notifications already sent to mentioned people stay.","x-platform-events":["conversation.note.created/1","conversation.mention.created/1"],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. A mentioned id or email is not an active staff member of your workspace (`reason: unknown_staff`), more than 20 people, a note with mentions is longer than 2000 characters, or has no `Idempotency-Key` header."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"ticket","summary":"Link a helpdesk ticket","path":{"conversation_id":"77410"},"query":{},"body":{"text":"Ticket #4411 opened in the helpdesk: https://help.example.com/tickets/4411"},"response":{"status":201,"body":{"note_id":"90331","conversation_id":"77410","visible_to_customer":false,"kind":"note","mentioned":[]}}},{"name":"mention","summary":"Ask a colleague to take a look","path":{"conversation_id":"77410"},"query":{},"body":{"text":"{{1203}} can you approve the refund for this order?","mention_staff_ids":["1203"],"mention_emails":["finance@example.com"]},"response":{"status":201,"body":{"note_id":"5501240","conversation_id":"77410","visible_to_customer":false,"kind":"mention","mentioned":[{"staff_id":"1203","name":"Priya Nair"},{"staff_id":"1207","name":"Finance Team"}]}}}]}},"/conversations/{conversation_id}/tags":{"post":{"operationId":"tagConversation","summary":"Tag a conversation","description":"Adds conversation tags by id and/or name; the conversation keeps its other tags, and adding a tag it already has changes nothing, so a retry is harmless. **A name that does not exist yet creates a new conversation tag in the workspace.** Unknown ids are skipped and listed in `ignored_tag_ids`.\n\nConversation tags are separate from contact tags.","tags":["inbox"],"security":[{"api_key":["inbox:write"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"The conversation id."},"x-platform-picker":"conversations"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag_ids":{"description":"Existing conversation tag ids.","maxItems":20,"type":"array","items":{"type":"string","pattern":"^\\d{1,19}$","description":"Tag id."}},"tag_names":{"description":"Tag names (1–50 characters). A new name creates the tag.","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":50}}},"additionalProperties":false},"examples":{"urgent":{"summary":"Flag a conversation as urgent","value":{"tag_names":["urgent"]}}}}}},"responses":{"200":{"description":"The conversation with all its tags.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversation":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":["string","null"]},"assignee_staff_id":{"type":["string","null"]},"team_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["id","state","assignee_staff_id","team_id","tags"],"additionalProperties":false},"ignored_tag_ids":{"type":"array","items":{"type":"string"}},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["conversation","ignored_tag_ids"]},"examples":{"urgent":{"summary":"Flag a conversation as urgent","value":{"conversation":{"id":"77410","state":"open","assignee_staff_id":null,"team_id":null,"tags":[{"id":"4","name":"new-lead"},{"id":"7","name":"urgent"}]},"ignored_tag_ids":[]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Neither `tag_ids` nor `tag_names` was given (up to 20 each).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Neither `tag_ids` nor `tag_names` was given (up to 20 each).","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Neither `tag_ids` nor `tag_names` was given (up to 20 each).","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_tag_conversation","x-platform-ops-path":"/ops/inbox_tag_conversation","x-platform-group":"inbox","x-platform-scope":"inbox:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Remove them with **Untag a conversation** (a tag created by name stays in the workspace).","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Neither `tag_ids` nor `tag_names` was given (up to 20 each)."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"urgent","summary":"Flag a conversation as urgent","path":{"conversation_id":"77410"},"query":{},"body":{"tag_names":["urgent"]},"response":{"status":200,"body":{"conversation":{"id":"77410","state":"open","assignee_staff_id":null,"team_id":null,"tags":[{"id":"4","name":"new-lead"},{"id":"7","name":"urgent"}]},"ignored_tag_ids":[]}}}]},"delete":{"operationId":"untagConversation","summary":"Untag a conversation","description":"Removes tags from a conversation, by id and/or name, given as query parameters (repeat one for several: `?tag_ids=4&tag_ids=7`). Tags the conversation does not have are ignored, so a retry is harmless. The tags themselves stay in the workspace.","tags":["inbox"],"security":[{"api_key":["inbox:write"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"The conversation id."},"x-platform-picker":"conversations"},{"name":"tag_ids","in":"query","required":false,"description":"Conversation tag ids to remove.","schema":{"description":"Conversation tag ids to remove.","maxItems":20,"type":"array","items":{"type":"string","pattern":"^\\d{1,19}$","description":"Tag id."}},"style":"form","explode":true},{"name":"tag_names","in":"query","required":false,"description":"Tag names to remove.","schema":{"description":"Tag names to remove.","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":50}},"style":"form","explode":true},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key"},{"$ref":"#/components/parameters/dry_run"}],"responses":{"200":{"description":"The conversation with its remaining tags.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"conversation":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":["string","null"]},"assignee_staff_id":{"type":["string","null"]},"team_id":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["id","state","assignee_staff_id","team_id","tags"],"additionalProperties":false},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["conversation"]},"examples":{"done":{"summary":"No longer urgent","value":{"conversation":{"id":"77410","state":"open","assignee_staff_id":null,"team_id":null,"tags":[{"id":"4","name":"new-lead"}]}}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. Neither `tag_ids` nor `tag_names` was given (up to 20 each).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. Neither `tag_ids` nor `tag_names` was given (up to 20 each).","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. Neither `tag_ids` nor `tag_names` was given (up to 20 each).","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_untag_conversation","x-platform-ops-path":"/ops/inbox_untag_conversation","x-platform-group":"inbox","x-platform-scope":"inbox:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"optional","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Add them back with **Tag a conversation**.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. Neither `tag_ids` nor `tag_names` was given (up to 20 each)."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"done","summary":"No longer urgent","path":{"conversation_id":"77410"},"query":{"tag_ids":["7"]},"response":{"status":200,"body":{"conversation":{"id":"77410","state":"open","assignee_staff_id":null,"team_id":null,"tags":[{"id":"4","name":"new-lead"}]}}}}]}},"/conversations/{conversation_id}/reminders":{"post":{"operationId":"createConversationReminder","summary":"Set a reminder","description":"Schedules a reminder on a conversation for your team, e.g. \"follow up on the quote\" tomorrow at 10:00. At that time the inbox notifies your team. **Nothing is sent to the customer.**\n\n`remind_at` is an ISO-8601 date-time with a timezone: `2026-10-02T10:00:00+04:00` or `2026-10-02T06:00:00Z`. It must be in the future (at least 30 seconds from now). The answer gives the time in UTC.","tags":["inbox"],"security":[{"api_key":["inbox:write"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"The conversation id."},"x-platform-picker":"conversations"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"remind_at":{"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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When to remind: ISO-8601 with a timezone offset or `Z`, in the future."},"note":{"type":"string","minLength":1,"maxLength":1000,"description":"What the reminder is about (1–1000 characters, staff only)."}},"required":["remind_at","note"],"additionalProperties":false},"examples":{"followup":{"summary":"Follow up on a quote tomorrow morning","value":{"remind_at":"2026-10-02T10:00:00+04:00","note":"Follow up on the quote for 20 units."}}}}}},"responses":{"201":{"description":"The reminder was set.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"reminder_id":{"type":"string"},"conversation_id":{"type":"string"},"remind_at":{"type":"string"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["reminder_id","conversation_id","remind_at"]},"examples":{"followup":{"summary":"Follow up on a quote tomorrow morning","value":{"reminder_id":"01J9ZK4QF7T3R8M2XW6N5B1C0D","conversation_id":"77410","remind_at":"2026-10-02T06:00:00.000Z"}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. `remind_at` has no timezone, or is not in the future. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. `remind_at` has no timezone, or is not in the future. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. `remind_at` has no timezone, or is not in the future. Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_create_reminder","x-platform-ops-path":"/ops/inbox_create_reminder","x-platform-group":"inbox","x-platform-scope":"inbox:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"required","x-platform-dry-run":"checks","x-platform-destructive-verb":null,"x-platform-undo":"Reminders can be deleted in the inbox.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. `remind_at` has no timezone, or is not in the future. Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"followup","summary":"Follow up on a quote tomorrow morning","path":{"conversation_id":"77410"},"query":{},"body":{"remind_at":"2026-10-02T10:00:00+04:00","note":"Follow up on the quote for 20 units."},"response":{"status":201,"body":{"reminder_id":"01J9ZK4QF7T3R8M2XW6N5B1C0D","conversation_id":"77410","remind_at":"2026-10-02T06:00:00.000Z"}}}]}},"/messages":{"post":{"operationId":"sendMessage","summary":"Send a message","description":"Sends one free-form message to a customer: text, media by public https link, a location, buttons, a list, a link button or a reaction. **The customer receives it and it cannot be undone.**\n\nSay who receives it with exactly one of:\n\n| Target | Channels | Goes into |\n| --- | --- | --- |\n| `conversation_id` | any | that conversation |\n| `contact_id` | any | the contact's conversation |\n| `phone` (the customer's number, international format such as `+15555550123`) | WhatsApp only | the conversation of the contact with that number |\n\nWith `contact_id` or `phone` you may also choose where it goes out from: `channel_id`, or `from_phone` (one of your connected WhatsApp numbers, in any format). When the contact has conversations on several channels and you name none, the one with an open reply window is used; when several are open you must choose (`400`, `reason: channel_ambiguous`, with the `choices`). Web chat and custom channels have no reply window, so they are never picked over a WhatsApp, Instagram, Messenger or TikTok conversation: name them with `channel_id` (they are picked by themselves only when the contact has no other kind of conversation). With `conversation_id` the conversation's own channel is used, so neither is accepted.\n\nA free-form message needs an open reply window where the channel has one (on WhatsApp, 24 hours after the customer's last message). The message always goes into the customer's existing conversation: when there is none on that channel (the customer never wrote there, or no contact has that number) or its window is closed, the answer is `409` with `reason: window_closed` and nothing is sent. Send an approved template with **Send a WhatsApp template** instead (`contact_id` is in the answer when the contact is known). A contact with do-not-disturb on is not messaged by `contact_id` or `phone` (`409`, `reason: contact_dnd`).\n\nThe key's staff member must be allowed to reply in that conversation. Customer messages count against the workspace send limits. Try it with `?dry_run=true`: every check runs and the answer shows the conversation, contact, channel and window it resolved to, but nothing is sent.","tags":["messages"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"description":"Target: reply in this conversation. Takes neither `channel_id` nor `from_phone`.","type":"string","pattern":"^\\d{1,19}$","x-platform-picker":"conversations"},"contact_id":{"description":"Target: this contact, in their existing conversation.","type":"string","pattern":"^\\d{1,19}$","x-platform-picker":"contacts"},"phone":{"description":"Target: the customer's WhatsApp number in international format, e.g. `+15555550123` (spaces and dashes are fine). WhatsApp only; the number must belong to one of your contacts.","type":"string","minLength":3,"maxLength":32},"channel_id":{"description":"With `contact_id` or `phone`: send on this channel. Needed when the contact has open conversations on several channels.","type":"string","pattern":"^\\d{1,19}$","x-platform-picker":"channels"},"from_phone":{"description":"With `contact_id` or `phone`, instead of `channel_id`: one of your connected WhatsApp numbers to send from, in any format.","type":"string","minLength":3,"maxLength":32},"type":{"type":"string","enum":["text","image","video","audio","document","sticker","location","interactive","reaction","system"],"description":"What to send: `text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `interactive` or `reaction`. Send exactly the one matching block."},"text":{"description":"type `text`: the message (1–4096 characters).","type":"string","minLength":1,"maxLength":4096},"reply_to_message_id":{"description":"Quote this message of the conversation (a message id from its message list).","type":"string","pattern":"^\\d{1,19}$"},"media":{"description":"type `image`, `video`, `audio`, `document` or `sticker`: `url`, a public https link to the file, with an optional `caption` (not for audio or stickers) and a `filename` for documents. The platform downloads the link when you send (it must answer directly, without a login or a redirect, within 60 seconds) and checks the file by its content: image JPEG or PNG up to 5 MB (WebP, GIF, HEIC and other images are converted), video MP4 or 3GP up to 16 MB, audio MP3, AAC, AMR, OGG or M4A up to 16 MB (other audio is converted), document PDF, Word, Excel or text up to 100 MB, sticker WebP up to 500 KB. The link must name its host on the default port (no IP address, port, user name, backslash or control character); a host that is private or internal, or that does not resolve, is refused (`reason: url_refused`, `private_address` or `dns_failed`). To send a file from your own system without hosting it, use **Send a file in a conversation** (`POST /v1/conversations/{conversation_id}/files`).","type":"object","properties":{"url":{"type":"string","maxLength":2000,"description":"Public https URL of the file (the platform downloads it)."},"caption":{"description":"Caption (image, video, document).","type":"string","maxLength":1024},"filename":{"description":"document: file name shown.","type":"string","maxLength":200}},"required":["url"]},"location":{"description":"type `location`: latitude, longitude, and an optional name and address.","type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude."},"name":{"description":"Place name.","type":"string","maxLength":255},"address":{"description":"Address.","type":"string","maxLength":255}},"required":["latitude","longitude"]},"interactive":{"description":"type `interactive`: `kind` `buttons` (1–3 quick replies), `list` (a menu of up to 10 rows) or `cta_url` (one link button).","type":"object","properties":{"kind":{"type":"string","enum":["buttons","list","cta_url"],"description":"buttons (1–3 quick replies), list (a menu), cta_url (one link button)."},"body":{"type":"string","minLength":1,"maxLength":1024,"description":"Message text (≤ 1024)."},"header":{"description":"Header text (≤ 60).","type":"string","maxLength":60},"footer":{"description":"Footer text (≤ 60).","type":"string","maxLength":60},"buttons":{"description":"kind buttons: 1–3 buttons, unique ids and titles.","minItems":1,"maxItems":3,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256,"description":"Reply id you get back when tapped."},"title":{"type":"string","minLength":1,"maxLength":20,"description":"Button text (≤ 20)."}},"required":["id","title"]}},"list_button":{"description":"kind list: the text of the button that opens the menu (≤ 20).","type":"string","minLength":1,"maxLength":20},"sections":{"description":"kind list: 1–10 sections, 10 rows in total at most.","minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"title":{"description":"Section title (≤ 24; needed with several sections).","type":"string","maxLength":24},"rows":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"Row id you get back."},"title":{"type":"string","minLength":1,"maxLength":24,"description":"Row title (≤ 24)."},"description":{"description":"Row description (≤ 72).","type":"string","maxLength":72}},"required":["id","title"]},"description":"Rows."}},"required":["rows"]}},"url":{"description":"kind cta_url: https link.","type":"string","maxLength":2000,"format":"uri"},"url_text":{"description":"kind cta_url: button text (≤ 20).","type":"string","minLength":1,"maxLength":20}},"required":["kind","body"]},"reaction":{"description":"type `reaction`: the message id to react to and one emoji (`\"\"` removes the reaction).","type":"object","properties":{"message_id":{"type":"string","pattern":"^\\d{1,19}$","description":"Message to react to (`GET /v1/conversations/{conversation_id}/messages` id)."},"emoji":{"type":"string","maxLength":16,"description":"One emoji; \"\" removes the reaction."}},"required":["message_id","emoji"]}},"required":["type"],"additionalProperties":false},"examples":{"by_phone":{"summary":"Message a customer by WhatsApp number, from one of your numbers","value":{"phone":"+15555550123","from_phone":"+1 555-555-0100","type":"text","text":"Your order #1001 is ready for pickup."}},"by_contact":{"summary":"Check a message to a contact on one channel (dry run)","value":{"contact_id":"48213","channel_id":"301","type":"text","text":"Thanks! Your refund was issued today."}}}}}},"responses":{"202":{"description":"Accepted for delivery (or the dry-run check), with the conversation, contact and channel it resolved to. Delivery and read receipts show as the message's `status` in the message list.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"message_id":{"type":["string","null"]},"status":{"type":"string","description":"queued (accepted for delivery), created (system line) or dry_run."},"type":{"type":"string"},"conversation_id":{"type":"string","description":"The conversation it went into (resolved from contactId / phone when those were given)."},"contact_id":{"description":"The customer it went to.","type":["string","null"]},"channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"type":{"type":"string"}},"required":["id","name","type"],"additionalProperties":false},"window":{"type":"object","properties":{"applies":{"type":"boolean","description":"false for channels without a window (web chat, custom) and for system messages."},"open":{"description":"null when the window does not apply.","type":["boolean","null"]},"kind":{"description":"service (24 h), free_entry (72 h after an ad), standard, tiktok (48 h), web.","type":["string","null"]},"closes_at":{"description":"Open window: when it closes.","type":["string","null"]},"closed_at":{"description":"Closed window: when it closed (null = the customer never wrote on this channel, or unknown).","type":["string","null"]}},"required":["applies","open","kind","closes_at","closed_at"],"additionalProperties":false},"visible_to_customer":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["message_id","status","type","conversation_id","contact_id","channel","window","visible_to_customer"]},"examples":{"by_phone":{"summary":"Message a customer by WhatsApp number, from one of your numbers","value":{"message_id":"5501239","status":"queued","type":"text","conversation_id":"77410","contact_id":"48213","channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null},"visible_to_customer":true}},"by_contact":{"summary":"Check a message to a contact on one channel (dry run)","value":{"message_id":null,"status":"dry_run","type":"text","conversation_id":"77410","contact_id":"48213","channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null},"visible_to_customer":true,"dry_run":true}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. No target or more than one (`reason: target_required`, `target_conflict`; also `channel_id` or `from_phone` with `conversation_id`, or both of them), a phone number that is not in international format (`reason: invalid_phone`), a `phone` target on a channel that is not WhatsApp (`reason: phone_needs_whatsapp`), several contacts with that number (`reason: contact_ambiguous`: send `contact_id`), a number that too many other contacts' numbers contain to find it exactly (`reason: lookup_incomplete`: send `contact_id`), open conversations on several channels and none chosen (`reason: channel_ambiguous`), or a message that breaks a rule (missing block, media link not public https, `reason: unsupported_on_channel`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. No target or more than one (`reason: target_required`, `target_conflict`; also `channel_id` or `from_phone` with `conversation_id`, or both of them), a phone number that is not in international format (`reason: invalid_phone`), a `phone` target on a channel that is not WhatsApp (`reason: phone_needs_whatsapp`), several contacts with that number (`reason: contact_ambiguous`: send `contact_id`), a number that too many other contacts' numbers contain to find it exactly (`reason: lookup_incomplete`: send `contact_id`), open conversations on several channels and none chosen (`reason: channel_ambiguous`), or a message that breaks a rule (missing block, media link not public https, `reason: unsupported_on_channel`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. No target or more than one (`reason: target_required`, `target_conflict`; also `channel_id` or `from_phone` with `conversation_id`, or both of them), a phone number that is not in international format (`reason: invalid_phone`), a `phone` target on a channel that is not WhatsApp (`reason: phone_needs_whatsapp`), several contacts with that number (`reason: contact_ambiguous`: send `contact_id`), a number that too many other contacts' numbers contain to find it exactly (`reason: lookup_incomplete`: send `contact_id`), open conversations on several channels and none chosen (`reason: channel_ambiguous`), or a message that breaks a rule (missing block, media link not public https, `reason: unsupported_on_channel`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The key's staff member may not reply in the conversation: it is closed, or assigned to someone else (`reason: cannot_send_here`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The key's staff member may not reply in the conversation: it is closed, or assigned to someone else (`reason: cannot_send_here`).","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The key's staff member may not reply in the conversation: it is closed, or assigned to someone else (`reason: cannot_send_here`).","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: The conversation, contact or channel is not in your workspace, or `from_phone` is not one of your connected WhatsApp numbers.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"The conversation, contact or channel is not in your workspace, or `from_phone` is not one of your connected WhatsApp numbers.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"The conversation, contact or channel is not in your workspace, or `from_phone` is not one of your connected WhatsApp numbers.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: No open reply window (`reason: window_closed`): there is no conversation with this customer on that channel, or its window closed. Send a template instead. Or the contact has do-not-disturb on (`reason: contact_dnd`), or the channel refused the message (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"No open reply window (`reason: window_closed`): there is no conversation with this customer on that channel, or its window closed. Send a template instead. Or the contact has do-not-disturb on (`reason: contact_dnd`), or the channel refused the message (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"No open reply window (`reason: window_closed`): there is no conversation with this customer on that channel, or its window closed. Send a template instead. Or the contact has do-not-disturb on (`reason: contact_dnd`), or the channel refused the message (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day).","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day).","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_send_message","x-platform-ops-path":"/ops/inbox_send_message","x-platform-group":"messages","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-send-caps":{"per_hour":20,"per_day":100,"per_recipient_per_day":3},"x-platform-idempotency":"required","x-platform-dry-run":"native","x-platform-destructive-verb":null,"x-platform-undo":"Cannot be undone: the customer receives the message.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. No target or more than one (`reason: target_required`, `target_conflict`; also `channel_id` or `from_phone` with `conversation_id`, or both of them), a phone number that is not in international format (`reason: invalid_phone`), a `phone` target on a channel that is not WhatsApp (`reason: phone_needs_whatsapp`), several contacts with that number (`reason: contact_ambiguous`: send `contact_id`), a number that too many other contacts' numbers contain to find it exactly (`reason: lookup_incomplete`: send `contact_id`), open conversations on several channels and none chosen (`reason: channel_ambiguous`), or a message that breaks a rule (missing block, media link not public https, `reason: unsupported_on_channel`). Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The key's staff member may not reply in the conversation: it is closed, or assigned to someone else (`reason: cannot_send_here`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"The conversation, contact or channel is not in your workspace, or `from_phone` is not one of your connected WhatsApp numbers."},{"code":"conflict","status":409,"when":"No open reply window (`reason: window_closed`): there is no conversation with this customer on that channel, or its window closed. Send a template instead. Or the contact has do-not-disturb on (`reason: contact_dnd`), or the channel refused the message (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap was reached (`reason: send_cap`, with `window`: hour, day or contact_day)."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"by_phone","summary":"Message a customer by WhatsApp number, from one of your numbers","path":{},"query":{},"body":{"phone":"+15555550123","from_phone":"+1 555-555-0100","type":"text","text":"Your order #1001 is ready for pickup."},"response":{"status":202,"body":{"message_id":"5501239","status":"queued","type":"text","conversation_id":"77410","contact_id":"48213","channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null},"visible_to_customer":true}}},{"name":"by_contact","summary":"Check a message to a contact on one channel (dry run)","path":{},"query":{"dry_run":true},"body":{"contact_id":"48213","channel_id":"301","type":"text","text":"Thanks! Your refund was issued today."},"response":{"status":202,"body":{"message_id":null,"status":"dry_run","type":"text","conversation_id":"77410","contact_id":"48213","channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null},"visible_to_customer":true,"dry_run":true}}}]}},"/conversations/{conversation_id}/system-messages":{"post":{"operationId":"addSystemMessage","summary":"Add a system message","description":"Adds a line to a conversation's thread that your team sees and **the customer never gets**: an event from your own systems, such as an order shipped, a payment received or a record synced. No reply window applies, and it does not count against the send limits.\n\n- `text`: the line (plain text, up to 4096 characters).\n- `system_type`: what kind of event it records, e.g. `ORDER_UPDATE`, `PAYMENT_RECEIVED` or `SHIPPING_UPDATE` (letters, digits and `_`, up to 100, upper-cased; default `NOTIFICATION`). The platform's own types (`MENTION`, `REMINDER`, `REMINDER_SET`, `REMINDER_ACKNOWLEDGED`, `REMINDER_DELETED`, `REMINDER_UPDATED`, `SLA_BREACH`, `CALL_EVENT`, `CLIENT_ACTION`) are refused: to mention colleagues, add a note instead.\n- `meta`: a JSON object kept with the line for integrations that read the thread later (at most 4 KB as JSON, nested at most 3 levels, 50 keys per object; keys are kept exactly as sent). The keys `mentionStaffs`, `acknowledged`, `reminder_id`, `created_by_staff_id` and `idempotency_key` are refused (send your key as the `Idempotency-Key` header).\n- `priority: true` moves the conversation up and notifies its assignee, a manager and the team leads; `meta.source` then appears in that notification, so it must be text (up to 200 characters) or a number.\n\nText and meta are shown as plain text, never as HTML. Try it with `?dry_run=true`: the conversation and the fields are checked and nothing is added.","tags":["messages"],"security":[{"api_key":["inbox:write"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"The conversation id."},"x-platform-picker":"conversations"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":4096,"description":"The line your team sees (plain text, 1–4096 characters)."},"system_type":{"description":"The kind of event, e.g. `ORDER_UPDATE` (letters, digits and `_`, up to 100; upper-cased; default `NOTIFICATION`). The platform's own types are refused.","type":"string","maxLength":100,"pattern":"^[A-Za-z][A-Za-z0-9_]*$"},"meta":{"description":"A JSON object kept with the line (at most 4 KB, 3 levels, 50 keys per object). Reserved keys are refused.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"priority":{"description":"`true` moves the conversation up and notifies its assignee, a manager and the team leads.","type":"boolean"}},"required":["text"],"additionalProperties":false},"examples":{"order_update":{"summary":"Record an order update for your team","value":{"text":"Order #4411 shipped with FedEx (tracking FX123456789).","system_type":"ORDER_UPDATE","meta":{"order_id":"4411","carrier":"FedEx","tracking_number":"FX123456789","source":"shop"}}}}}}},"responses":{"201":{"description":"The line was added (or the dry-run check). It shows in the conversation's message list as a `SYSTEM` message.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"message_id":{"type":["string","null"]},"status":{"type":"string","description":"created, or dry_run."},"conversation_id":{"type":"string"},"channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"type":{"type":"string"}},"required":["id","name","type"],"additionalProperties":false},"system_type":{"type":"string"},"visible_to_customer":{"type":"boolean"},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["message_id","status","conversation_id","channel","system_type","visible_to_customer"]},"examples":{"order_update":{"summary":"Record an order update for your team","value":{"message_id":"5501238","status":"created","conversation_id":"77410","channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"system_type":"ORDER_UPDATE","visible_to_customer":false}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. `text` is empty or too long, `system_type` is reserved for the platform or has other characters, or `meta` breaks a rule (a reserved key, too large or too deep, or a `source` that is not text up to 200 characters or a number). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. `text` is empty or too long, `system_type` is reserved for the platform or has other characters, or `meta` breaks a rule (a reserved key, too large or too deep, or a `source` that is not text up to 200 characters or a number). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. `text` is empty or too long, `system_type` is reserved for the platform or has other characters, or `meta` breaks a rule (a reserved key, too large or too deep, or a `source` that is not text up to 200 characters or a number). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id, or your key cannot see it.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id, or your key cannot see it.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id, or your key cannot see it.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_add_system_message","x-platform-ops-path":"/ops/inbox_add_system_message","x-platform-group":"messages","x-platform-scope":"inbox:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-idempotency":"required","x-platform-dry-run":"native","x-platform-destructive-verb":null,"x-platform-undo":"A system line cannot be removed.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. `text` is empty or too long, `system_type` is reserved for the platform or has other characters, or `meta` breaks a rule (a reserved key, too large or too deep, or a `source` that is not text up to 200 characters or a number). Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id, or your key cannot see it."},{"code":"conflict","status":409,"when":"Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"order_update","summary":"Record an order update for your team","path":{"conversation_id":"77410"},"query":{},"body":{"text":"Order #4411 shipped with FedEx (tracking FX123456789).","system_type":"ORDER_UPDATE","meta":{"order_id":"4411","carrier":"FedEx","tracking_number":"FX123456789","source":"shop"}},"response":{"status":201,"body":{"message_id":"5501238","status":"created","conversation_id":"77410","channel":{"id":"301","name":"Main WhatsApp","type":"whatsapp"},"system_type":"ORDER_UPDATE","visible_to_customer":false}}}]}},"/conversations/{conversation_id}/files":{"post":{"operationId":"sendConversationFile","summary":"Send a file in a conversation","description":"Uploads a file and sends it to the customer in a conversation, in one request: a PDF, an Office document, a photo, a voice note or other audio, a video or a text file, with an optional caption. **The customer receives it and it cannot be undone.** Nothing is kept on our side after the answer, so there is no upload step and no upload id: to send the same file again, send it again (or host it and use **Send a message in a conversation** with `media.url`).\n\nSend the file as `multipart/form-data` with a `file` part (recommended; any HTTP client or `curl -F` builds it):\n\n```bash\ncurl https://mcp.wa-api.cloud/v1/conversations/77410/files \\\n  -H \"Authorization: Bearer ${env_var_name}\" \\\n  -H \"Idempotency-Key: 5f1c2d9e-invoice-1001\" \\\n  -F file=@invoice-1001.pdf \\\n  -F caption=\"Your invoice\"\n```\n\nor as JSON with the file in `content_base64` (with `filename`), which suits small files: a JSON body is about a third larger than the file.\n\n**What can be sent.** The file's content decides its type, whatever its name or declared type says; a declared type that does not match the content is refused (`reason: content_mismatch`). Accepted: PDF, JPEG, PNG, WebP, MP4, 3GP, MP3, OGG, AAC, AMR, DOCX, XLSX, PPTX, plain text and CSV. Executables, scripts, HTML, SVG, XML and other archives are refused (`reason: unsupported_type`). A file is at most 10 MB (the answer names this server's limit). Images go as images up to 5 MB; a larger image, or any file with `as_document: true`, goes as a document. Audio has no caption. A video may go as a document on channels that cannot take a video file yet (the answer's `note` says so).\n\nLike any free-form message it needs an open reply window where the channel has one (on WhatsApp, 24 hours after the customer's last message): otherwise `409` with `reason: window_closed` (send an approved template instead). The key's staff member must be allowed to reply in the conversation. Files count against the workspace send limits and the workspace's file upload limits (files per hour and per day, and megabytes per day: `429` with `reason: upload_cap` or `upload_bytes_cap`). Try it with `?dry_run=true` (or a test key): the file is read and every check runs, and nothing is sent or kept.","tags":["messages"],"security":[{"api_key":["messaging:write"]}],"parameters":[{"name":"conversation_id","in":"path","required":true,"description":"The conversation id.","schema":{"type":"string","pattern":"^\\d{1,19}$","description":"The conversation id."},"x-platform-picker":"conversations"},{"$ref":"#/components/parameters/Api-Version"},{"$ref":"#/components/parameters/Idempotency-Key-Required"},{"$ref":"#/components/parameters/dry_run"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content_base64":{"description":"JSON body: the file itself, base64-encoded (standard or URL-safe alphabet). With `multipart/form-data` send the `file` part instead.","type":"string","maxLength":140000000},"filename":{"description":"The file name the customer sees, e.g. `invoice-1001.pdf` (up to 200 characters; any path is removed and the extension is set from the content).","type":"string","minLength":1,"maxLength":200},"content_type":{"description":"The file's type as you know it, e.g. `application/pdf`. Optional: the content decides, and a type that does not match it is refused.","type":"string","maxLength":120},"caption":{"description":"Text shown with the file (up to 1024 characters; not for audio).","type":"string","maxLength":1024},"as_document":{"description":"`true` sends the file as a document whatever its type (e.g. a photo in full quality, or an image over 5 MB).","type":"boolean"}},"required":["content_base64","filename"],"additionalProperties":false},"examples":{"json_small_file":{"summary":"Send a small text file as JSON (base64)","value":{"content_base64":"T3JkZXIgIzEwMDE6IDIgaXRlbXMsIHRvdGFsICQ0MC4wMAo=","filename":"order-1001.txt","content_type":"text/plain","caption":"Your order summary"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file, as a form file part: its file name and Content-Type are used unless `filename` / `content_type` are sent. The content decides the type (see `encoding`); anything else is refused."},"filename":{"description":"The file name the customer sees, e.g. `invoice-1001.pdf` (up to 200 characters; any path is removed and the extension is set from the content). Optional here: the file part's own file name is used by default.","type":"string","minLength":1,"maxLength":200},"content_type":{"description":"The file's type as you know it, e.g. `application/pdf`. Optional: the content decides, and a type that does not match it is refused. Optional here: the file part's own Content-Type is used by default.","type":"string","maxLength":120},"caption":{"description":"Text shown with the file (up to 1024 characters; not for audio).","type":"string","maxLength":1024},"as_document":{"description":"`true` sends the file as a document whatever its type (e.g. a photo in full quality, or an image over 5 MB).","type":"boolean"}},"required":["file"],"additionalProperties":false},"encoding":{"file":{"contentType":"application/pdf, image/jpeg, image/png, image/webp, video/mp4, video/3gpp, audio/mpeg, audio/ogg, audio/aac, audio/amr, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.presentationml.presentation, text/plain, text/csv"}}}}},"responses":{"202":{"description":"Accepted for delivery (or the dry-run check): how the file went (`sent_as`: `image`, `video`, `audio` or `document`) and the file as it was sent. Delivery and read receipts show as the message's `status` in the message list.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"message_id":{"description":"null for a dry run.","type":["string","null"]},"status":{"type":"string","description":"queued, or dry_run."},"conversation_id":{"type":"string"},"sent_as":{"type":"string","description":"image, video, audio or document."},"file":{"type":"object","properties":{"name":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"number"}},"required":["name","content_type","size_bytes"],"additionalProperties":false},"channel":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"window":{"type":"object","properties":{"applies":{"type":"boolean","description":"false for channels without a window (web chat, custom) and for system messages."},"open":{"description":"null when the window does not apply.","type":["boolean","null"]},"kind":{"description":"service (24 h), free_entry (72 h after an ad), standard, tiktok (48 h), web.","type":["string","null"]},"closes_at":{"description":"Open window: when it closes.","type":["string","null"]},"closed_at":{"description":"Closed window: when it closed (null = the customer never wrote on this channel, or unknown).","type":["string","null"]}},"required":["applies","open","kind","closes_at","closed_at"],"additionalProperties":false},"note":{"type":["string","null"]},"dry_run":{"type":"boolean","description":"`true` when this was a dry run: every check ran and nothing changed."}},"required":["message_id","status","conversation_id","sent_as","file","channel","window","note"]},"examples":{"json_small_file":{"summary":"Send a small text file as JSON (base64)","value":{"message_id":"5501240","status":"queued","conversation_id":"77410","sent_as":"document","file":{"name":"order-1001.txt","content_type":"text/plain","size_bytes":35},"channel":{"id":"301","type":"whatsapp"},"window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null},"note":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. No file (`/file`), a file type that cannot be sent (`reason: unsupported_type`), content that is not the declared type (`reason: content_mismatch`), a file over the limit (`reason: too_large`) or an image over 5 MB not sent as a document (`reason: too_large_for_type`), a caption on audio, a malformed multipart body (`reason: invalid_multipart`), a body over the limit (`reason: body_too_large`: the file limit plus 64 KB for multipart, a third more for JSON), or a body that stopped arriving for 30 seconds (`reason: body_timeout`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. No file (`/file`), a file type that cannot be sent (`reason: unsupported_type`), content that is not the declared type (`reason: content_mismatch`), a file over the limit (`reason: too_large`) or an image over 5 MB not sent as a document (`reason: too_large_for_type`), a caption on audio, a malformed multipart body (`reason: invalid_multipart`), a body over the limit (`reason: body_too_large`: the file limit plus 64 KB for multipart, a third more for JSON), or a body that stopped arriving for 30 seconds (`reason: body_timeout`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. No file (`/file`), a file type that cannot be sent (`reason: unsupported_type`), content that is not the declared type (`reason: content_mismatch`), a file over the limit (`reason: too_large`) or an image over 5 MB not sent as a document (`reason: too_large_for_type`), a caption on audio, a malformed multipart body (`reason: invalid_multipart`), a body over the limit (`reason: body_too_large`: the file limit plus 64 KB for multipart, a third more for JSON), or a body that stopped arriving for 30 seconds (`reason: body_timeout`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The key's staff member may not reply here: the conversation is closed, or assigned to someone else (`reason: cannot_send_here`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The key's staff member may not reply here: the conversation is closed, or assigned to someone else (`reason: cannot_send_here`).","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The key's staff member may not reply here: the conversation is closed, or assigned to someone else (`reason: cannot_send_here`).","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"404":{"description":"`not_found`: No conversation with this id, or your key cannot see it.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"No conversation with this id, or your key cannot see it.","value":{"type":"https://dev.wa-api.cloud/errors/not_found","title":"Not found","status":404,"detail":"No conversation with this id, or your key cannot see it.","code":"not_found","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"409":{"description":"`conflict`: The customer's reply window is closed (`reason: window_closed`): send a template instead. Or the channel refused the file (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"The customer's reply window is closed (`reason: window_closed`): send a template instead. Or the channel refused the file (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running.","value":{"type":"https://dev.wa-api.cloud/errors/conflict","title":"Conflicts with the current state","status":409,"detail":"The customer's reply window is closed (`reason: window_closed`): send a template instead. Or the channel refused the file (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running.","code":"conflict","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap (`reason: send_cap`) or a file upload cap (`reason: upload_cap`, files per hour or day; `reason: upload_bytes_cap`, megabytes per day) was reached, or too many files are being sent at once — on the server, or two at a time by one workspace (`reason: busy`: retry in a few seconds).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap (`reason: send_cap`) or a file upload cap (`reason: upload_cap`, files per hour or day; `reason: upload_bytes_cap`, megabytes per day) was reached, or too many files are being sent at once — on the server, or two at a time by one workspace (`reason: busy`: retry in a few seconds).","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap (`reason: send_cap`) or a file upload cap (`reason: upload_cap`, files per hour or day; `reason: upload_bytes_cap`, megabytes per day) was reached, or too many files are being sent at once — on the server, or two at a time by one workspace (`reason: busy`: retry in a few seconds).","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"504":{"description":"`timeout`: The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"timeout":{"summary":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","value":{"type":"https://dev.wa-api.cloud/errors/timeout","title":"The request took too long","status":504,"detail":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.","code":"timeout","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"inbox_send_file","x-platform-ops-path":"/ops/inbox_send_file","x-platform-group":"messages","x-platform-scope":"messaging:write","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"write","per_minute":60,"burst":60},"x-platform-send-caps":{"per_hour":20,"per_day":100,"per_recipient_per_day":3},"x-platform-idempotency":"required","x-platform-dry-run":"native","x-platform-destructive-verb":null,"x-platform-undo":"Cannot be undone: the customer receives the file.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. No file (`/file`), a file type that cannot be sent (`reason: unsupported_type`), content that is not the declared type (`reason: content_mismatch`), a file over the limit (`reason: too_large`) or an image over 5 MB not sent as a document (`reason: too_large_for_type`), a caption on audio, a malformed multipart body (`reason: invalid_multipart`), a body over the limit (`reason: body_too_large`: the file limit plus 64 KB for multipart, a third more for JSON), or a body that stopped arriving for 30 seconds (`reason: body_timeout`). Also returned when the Idempotency-Key header is missing, or was used before with a different body."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The key's staff member may not reply here: the conversation is closed, or assigned to someone else (`reason: cannot_send_here`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"not_found","status":404,"when":"No conversation with this id, or your key cannot see it."},{"code":"conflict","status":409,"when":"The customer's reply window is closed (`reason: window_closed`): send a template instead. Or the channel refused the file (`reason: send_failed`). Also returned while a request with the same Idempotency-Key is still running."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds. A send cap (`reason: send_cap`) or a file upload cap (`reason: upload_cap`, files per hour or day; `reason: upload_bytes_cap`, megabytes per day) was reached, or too many files are being sent at once — on the server, or two at a time by one workspace (`reason: busy`: retry in a few seconds)."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."},{"code":"timeout","status":504,"when":"The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice."}],"x-platform-examples":[{"name":"json_small_file","summary":"Send a small text file as JSON (base64)","path":{"conversation_id":"77410"},"query":{},"body":{"content_base64":"T3JkZXIgIzEwMDE6IDIgaXRlbXMsIHRvdGFsICQ0MC4wMAo=","filename":"order-1001.txt","content_type":"text/plain","caption":"Your order summary"},"response":{"status":202,"body":{"message_id":"5501240","status":"queued","conversation_id":"77410","sent_as":"document","file":{"name":"order-1001.txt","content_type":"text/plain","size_bytes":35},"channel":{"id":"301","type":"whatsapp"},"window":{"applies":true,"open":true,"kind":"service","closes_at":"2026-09-25T09:12:00.000Z","closed_at":null},"note":null}}}]}},"/reports/summary":{"get":{"operationId":"getWorkspaceSummaryReport","summary":"Workspace summary","description":"One call for the headline numbers of a period: messages, conversations, new contacts, broadcasts and SLA breaches.\n\nA metric this workspace cannot answer is `null` and listed in `unavailable[]` with the reason. **Never read `null` as zero.**","tags":["reports"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"preset","in":"query","required":false,"description":"A named period. Default `last_7_days`. Weeks start on Monday.","schema":{"description":"A named period. Default `last_7_days`. Weeks start on Monday.","type":"string","enum":["today","yesterday","last_7_days","last_14_days","last_30_days","this_month","last_month","this_week","last_week"]}},{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","schema":{"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Last day (inclusive), YYYY-MM-DD.","schema":{"description":"Last day (inclusive), YYYY-MM-DD.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"timezone","in":"query","required":false,"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","schema":{"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","type":"string","minLength":1,"maxLength":64}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The summary.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"range":{"type":"object","properties":{"from":{"type":"string","description":"First local day (YYYY-MM-DD), inclusive."},"to":{"type":"string","description":"Last local day (YYYY-MM-DD), inclusive."},"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of local days in the range."},"timezone":{"type":"string","description":"IANA timezone the days were counted in."},"started_at":{"type":"string","description":"Range start as a UTC instant (ISO-8601)."},"ended_at":{"type":"string","description":"Range end as a UTC instant (ISO-8601), exclusive."},"preset":{"description":"The named range used, if any.","type":["string","null"]}},"required":["from","to","days","timezone","started_at","ended_at","preset"],"additionalProperties":false,"description":"The range and timezone these numbers were counted in — always state it when reporting them."},"workspace":{"type":"object","properties":{"company_id":{"type":["string","null"]},"name":{"type":["string","null"]},"timezone":{"description":"The workspace timezone the platform holds; the range above says which timezone was actually used.","type":["string","null"]},"contacts_total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"All contacts ever (not the range)."}},"required":["company_id","name","timezone","contacts_total"],"additionalProperties":false},"messages":{"type":"object","properties":{"sent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"delivered":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"read":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"failed":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"delivery_rate":{"type":["number","null"]}},"required":["sent","delivered","read","failed","delivery_rate"],"additionalProperties":false},"conversations":{"type":"object","properties":{"closes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Conversations closed in the range (closing events)."},"distinct_conversations":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"reopened":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"median_close_seconds":{"type":["number","null"]},"waiting_now":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Waiting on us right now (live, not part of the range)."},"unassigned_now":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"oldest_wait_buckets_now":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},{"type":"null"}]}},"required":["closes","distinct_conversations","reopened","median_close_seconds","waiting_now","unassigned_now","oldest_wait_buckets_now"],"additionalProperties":false},"contacts":{"type":"object","properties":{"new":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Contacts created in the range."},"new_is_lower_bound":{"type":"boolean","description":"true = the platform has no count-by-date, the walk was cut short, and \"new\" is a minimum."}},"required":["new","new_is_lower_bound"],"additionalProperties":false},"broadcasts":{"type":"object","properties":{"started":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"delivered":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"read":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"failed":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"opted_out":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["started","sent","delivered","read","failed","opted_out"],"additionalProperties":false},"sla":{"type":"object","properties":{"running":{"description":"Is SLA active for this workspace (plan AND module switch)?","type":["boolean","null"]},"breaches":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"config_problems":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["running","breaches","config_problems"],"additionalProperties":false},"agents":{"type":"object","properties":{"sessions":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"AI-agent conversations started in the range (studio tests excluded)."},"handoffs":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Of those, handed over to a human."},"resolution_rate":{"type":["number","null"]}},"required":["sessions","handoffs","resolution_rate"],"additionalProperties":false},"chatbots":{"type":"object","properties":{"sessions":{"type":"null","description":"Always null: The platform keeps no chatbot usage analytics."}},"required":["sessions"],"additionalProperties":false},"notes":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string","description":"Which metric or section is missing, e.g. \"messages.read\"."},"reason":{"type":"string","description":"Why it is missing (not supported by this server version, service not configured, forbidden, temporarily unavailable…)."}},"required":["metric","reason"],"additionalProperties":false,"description":"A metric this workspace cannot answer right now. Treat it as unknown — never as zero."},"description":"Metrics that are UNKNOWN (missing data source), not zero. Say so when reporting; do not fill them in with 0."}},"required":["range","workspace","messages","conversations","contacts","broadcasts","sla","agents","chatbots","notes","unavailable"]},"examples":{"week":{"summary":"Last 7 days","value":{"range":{"from":"2026-09-17","to":"2026-09-23","days":7,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"last_7_days"},"messages":{"sent":1840,"delivered":1791,"read":1422,"failed":12,"delivery_rate":0.973},"conversations":{"closes":406,"reopened":31,"median_close_seconds":5400,"waiting_now":9,"unassigned_now":4,"distinct_conversations":null,"oldest_wait_buckets_now":null},"contacts":{"new":233,"new_is_lower_bound":false},"broadcasts":{"started":3,"sent":5210,"delivered":5096,"failed":44,"read":null,"opted_out":null},"sla":{"breaches":7,"running":null,"config_problems":null},"notes":[],"unavailable":[],"workspace":{"company_id":null,"name":null,"timezone":null,"contacts_total":null},"agents":{"sessions":null,"handoffs":null,"resolution_rate":null},"chatbots":{"sessions":null}}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"reports_workspace_summary","x-platform-ops-path":"/ops/reports_workspace_summary","x-platform-group":"reports","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"stable","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"week","summary":"Last 7 days","path":{},"query":{"preset":"last_7_days"},"response":{"status":200,"body":{"range":{"from":"2026-09-17","to":"2026-09-23","days":7,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"last_7_days"},"messages":{"sent":1840,"delivered":1791,"read":1422,"failed":12,"delivery_rate":0.973},"conversations":{"closes":406,"reopened":31,"median_close_seconds":5400,"waiting_now":9,"unassigned_now":4,"distinct_conversations":null,"oldest_wait_buckets_now":null},"contacts":{"new":233,"new_is_lower_bound":false},"broadcasts":{"started":3,"sent":5210,"delivered":5096,"failed":44,"read":null,"opted_out":null},"sla":{"breaches":7,"running":null,"config_problems":null},"notes":[],"unavailable":[],"workspace":{"company_id":null,"name":null,"timezone":null,"contacts_total":null},"agents":{"sessions":null,"handoffs":null,"resolution_rate":null},"chatbots":{"sessions":null}}}}]}},"/reports/messaging":{"get":{"operationId":"getMessagingReport","summary":"Messaging report","description":"Outbound message volume for a period — sent, delivered, read and failed — per day and per WhatsApp number. \"Read\" depends on customers' read receipts.\n\nA metric this workspace cannot answer is `null` and listed in `unavailable[]` with the reason. **Never read `null` as zero.**","tags":["reports"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"preset","in":"query","required":false,"description":"A named period. Default `last_7_days`. Weeks start on Monday.","schema":{"description":"A named period. Default `last_7_days`. Weeks start on Monday.","type":"string","enum":["today","yesterday","last_7_days","last_14_days","last_30_days","this_month","last_month","this_week","last_week"]}},{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","schema":{"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Last day (inclusive), YYYY-MM-DD.","schema":{"description":"Last day (inclusive), YYYY-MM-DD.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"timezone","in":"query","required":false,"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","schema":{"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","type":"string","minLength":1,"maxLength":64}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The report.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"range":{"type":"object","properties":{"from":{"type":"string","description":"First local day (YYYY-MM-DD), inclusive."},"to":{"type":"string","description":"Last local day (YYYY-MM-DD), inclusive."},"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of local days in the range."},"timezone":{"type":"string","description":"IANA timezone the days were counted in."},"started_at":{"type":"string","description":"Range start as a UTC instant (ISO-8601)."},"ended_at":{"type":"string","description":"Range end as a UTC instant (ISO-8601), exclusive."},"preset":{"description":"The named range used, if any.","type":["string","null"]}},"required":["from","to","days","timezone","started_at","ended_at","preset"],"additionalProperties":false,"description":"The range and timezone these numbers were counted in — always state it when reporting them."},"totals":{"type":"object","properties":{"sent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Outbound, non-bot messages the platform accepted for sending in the range."},"delivered":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Of those, confirmed delivered to the handset."},"read":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Of those, marked read. Depends on the customer having read receipts on — a low number is not proof nobody read."},"failed":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Rejected or failed (Meta error, invalid number, no open window)."},"delivery_rate":{"description":"delivered / sent (0-1); null when nothing was sent.","type":["number","null"]},"read_rate":{"description":"read / delivered (0-1); null when nothing was delivered.","type":["number","null"]},"failure_rate":{"description":"failed / sent (0-1); null when nothing was sent.","type":["number","null"]}},"required":["sent","delivered","read","failed","delivery_rate","read_rate","failure_rate"],"additionalProperties":false},"by_day":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Local calendar day (YYYY-MM-DD) in the reported timezone."},"sent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"delivered":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["date","sent","delivered"],"additionalProperties":false},"description":"Per local day. Empty when no daily source is available (see unavailable[])."},"by_channel":{"type":"array","items":{"type":"object","properties":{"channel_id":{"type":"string"},"name":{"type":["string","null"]},"type":{"type":["string","null"]},"sent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"delivered":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["channel_id","name","type","sent","delivered"],"additionalProperties":false},"description":"Per WhatsApp number. Empty when the WhatsApp service is not connected or has no numbers."},"template_stats":{"type":"null","description":"Always null: no service in this stack exposes per-template sends, delivery or read rates."},"notes":{"type":"array","items":{"type":"string"},"description":"How to read these numbers (sources, boundaries, caveats)."},"unavailable":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string","description":"Which metric or section is missing, e.g. \"messages.read\"."},"reason":{"type":"string","description":"Why it is missing (not supported by this server version, service not configured, forbidden, temporarily unavailable…)."}},"required":["metric","reason"],"additionalProperties":false,"description":"A metric this workspace cannot answer right now. Treat it as unknown — never as zero."},"description":"Metrics that are UNKNOWN (missing data source), not zero. Say so when reporting; do not fill them in with 0."}},"required":["range","totals","by_day","by_channel","template_stats","notes","unavailable"]},"examples":{"month":{"summary":"Last month","value":{"range":{"from":"2026-08-01","to":"2026-08-31","days":31,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"last_month"},"totals":{"sent":8120,"delivered":7911,"read":6002,"failed":64,"delivery_rate":0.974,"read_rate":0.759,"failure_rate":null},"by_day":[{"date":"2026-08-31","sent":260,"delivered":255}],"by_channel":[{"channel_id":"301","name":"Main WhatsApp","sent":8120,"delivered":7911,"type":null}],"notes":[],"unavailable":[],"template_stats":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"reports_messaging","x-platform-ops-path":"/ops/reports_messaging","x-platform-group":"reports","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"month","summary":"Last month","path":{},"query":{"preset":"last_month"},"response":{"status":200,"body":{"range":{"from":"2026-08-01","to":"2026-08-31","days":31,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"last_month"},"totals":{"sent":8120,"delivered":7911,"read":6002,"failed":64,"delivery_rate":0.974,"read_rate":0.759,"failure_rate":null},"by_day":[{"date":"2026-08-31","sent":260,"delivered":255}],"by_channel":[{"channel_id":"301","name":"Main WhatsApp","sent":8120,"delivered":7911,"type":null}],"notes":[],"unavailable":[],"template_stats":null}}}]}},"/reports/broadcasts":{"get":{"operationId":"getBroadcastsReport","summary":"Broadcasts report","description":"Broadcasts created in a period, newest first, each with audience, sent, delivered, read, failed and opted-out counts. Test sends are left out unless you ask.\n\nA metric this workspace cannot answer is `null` and listed in `unavailable[]` with the reason. **Never read `null` as zero.**","tags":["reports"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"preset","in":"query","required":false,"description":"A named period. Default `last_7_days`. Weeks start on Monday.","schema":{"description":"A named period. Default `last_7_days`. Weeks start on Monday.","type":"string","enum":["today","yesterday","last_7_days","last_14_days","last_30_days","this_month","last_month","this_week","last_week"]}},{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","schema":{"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Last day (inclusive), YYYY-MM-DD.","schema":{"description":"Last day (inclusive), YYYY-MM-DD.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"timezone","in":"query","required":false,"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","schema":{"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","type":"string","minLength":1,"maxLength":64}},{"name":"include_sandbox","in":"query","required":false,"description":"Include test broadcasts.","schema":{"default":false,"description":"Include test broadcasts.","type":"boolean"}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of broadcasts.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"range":{"type":"object","properties":{"from":{"type":"string","description":"First local day (YYYY-MM-DD), inclusive."},"to":{"type":"string","description":"Last local day (YYYY-MM-DD), inclusive."},"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of local days in the range."},"timezone":{"type":"string","description":"IANA timezone the days were counted in."},"started_at":{"type":"string","description":"Range start as a UTC instant (ISO-8601)."},"ended_at":{"type":"string","description":"Range end as a UTC instant (ISO-8601), exclusive."},"preset":{"description":"The named range used, if any.","type":["string","null"]}},"required":["from","to","days","timezone","started_at","ended_at","preset"],"additionalProperties":false,"description":"The range and timezone these numbers were counted in — always state it when reporting them."},"totals":{"type":"object","properties":{"broadcasts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"audience":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"delivered":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"read":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"opted_out":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"delivery_rate":{"type":["number","null"]},"read_rate":{"type":["number","null"]}},"required":["broadcasts","audience","sent","delivered","read","failed","opted_out","delivery_rate","read_rate"],"additionalProperties":false},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"status":{"type":["string","null"]},"created_at":{"type":["string","null"]},"sandbox":{"type":"boolean","description":"true = a test send, not real traffic."},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"template":{"anyOf":[{"type":"object","properties":{"name":{"type":["string","null"]},"language":{"type":["string","null"]}},"required":["name","language"],"additionalProperties":false},{"type":"null"}]},"stats":{"type":"object","properties":{"audience":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Recipients in the audience (summary total, or the estimate before sending started)."},"sent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"delivered":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"read":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Marked read — depends on the recipient having read receipts on."},"failed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pending":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"opted_out":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Skipped because the contact is on do-not-disturb / opted out."},"responded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"delivery_rate":{"type":["number","null"]},"read_rate":{"type":["number","null"]}},"required":["audience","sent","delivered","read","failed","pending","opted_out","responded","delivery_rate","read_rate"],"additionalProperties":false}},"required":["id","name","status","created_at","sandbox","channel","template","stats"],"additionalProperties":false},"description":"One page of broadcasts, newest first."},"scanned":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Broadcasts inspected while walking the list to cover the range."},"truncated":{"type":"boolean","description":"true = the walk stopped early (page budget or time); older broadcasts in the range may be missing and the totals are a lower bound."},"notes":{"type":"array","items":{"type":"string"}},"next_cursor":{"description":"Pass as \"cursor\" for the next page; null when there are no more.","type":["string","null"]},"unavailable":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string","description":"Which metric or section is missing, e.g. \"messages.read\"."},"reason":{"type":"string","description":"Why it is missing (not supported by this server version, service not configured, forbidden, temporarily unavailable…)."}},"required":["metric","reason"],"additionalProperties":false,"description":"A metric this workspace cannot answer right now. Treat it as unknown — never as zero."},"description":"Metrics that are UNKNOWN (missing data source), not zero. Say so when reporting; do not fill them in with 0."}},"required":["range","totals","data","scanned","truncated","notes","next_cursor","unavailable"]},"examples":{"month":{"summary":"This month","value":{"data":[{"id":"8812","name":"September sale","status":"COMPLETED","created_at":"2026-09-15T07:00:00Z","channel":{"id":"301","name":"Main WhatsApp"},"template":{"name":"sept_sale","language":"en_US"},"stats":{"audience":5300,"sent":5210,"delivered":5096,"read":3920,"failed":44,"opted_out":18,"pending":-9007199254740991,"responded":-9007199254740991,"delivery_rate":null,"read_rate":null},"sandbox":false}],"next_cursor":null,"range":{"from":"2026-09-01","to":"2026-09-23","days":23,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"this_month"},"unavailable":[],"totals":{"broadcasts":-9007199254740991,"audience":-9007199254740991,"sent":-9007199254740991,"delivered":-9007199254740991,"read":-9007199254740991,"failed":-9007199254740991,"opted_out":-9007199254740991,"delivery_rate":null,"read_rate":null},"scanned":-9007199254740991,"truncated":false,"notes":[]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"reports_broadcasts","x-platform-ops-path":"/ops/reports_broadcasts","x-platform-group":"reports","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"month","summary":"This month","path":{},"query":{"preset":"this_month"},"response":{"status":200,"body":{"data":[{"id":"8812","name":"September sale","status":"COMPLETED","created_at":"2026-09-15T07:00:00Z","channel":{"id":"301","name":"Main WhatsApp"},"template":{"name":"sept_sale","language":"en_US"},"stats":{"audience":5300,"sent":5210,"delivered":5096,"read":3920,"failed":44,"opted_out":18,"pending":-9007199254740991,"responded":-9007199254740991,"delivery_rate":null,"read_rate":null},"sandbox":false}],"next_cursor":null,"range":{"from":"2026-09-01","to":"2026-09-23","days":23,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"this_month"},"unavailable":[],"totals":{"broadcasts":-9007199254740991,"audience":-9007199254740991,"sent":-9007199254740991,"delivered":-9007199254740991,"read":-9007199254740991,"failed":-9007199254740991,"opted_out":-9007199254740991,"delivery_rate":null,"read_rate":null},"scanned":-9007199254740991,"truncated":false,"notes":[]}}}]}},"/reports/conversations":{"get":{"operationId":"getConversationsReport","summary":"Conversations report","description":"Conversation outcomes for a period: closes, close reasons, reopen rate and median time to close, per day and per channel — plus how many customers are waiting right now.\n\nA metric this workspace cannot answer is `null` and listed in `unavailable[]` with the reason. **Never read `null` as zero.**","tags":["reports"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"preset","in":"query","required":false,"description":"A named period. Default `last_7_days`. Weeks start on Monday.","schema":{"description":"A named period. Default `last_7_days`. Weeks start on Monday.","type":"string","enum":["today","yesterday","last_7_days","last_14_days","last_30_days","this_month","last_month","this_week","last_week"]}},{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","schema":{"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Last day (inclusive), YYYY-MM-DD.","schema":{"description":"Last day (inclusive), YYYY-MM-DD.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"timezone","in":"query","required":false,"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","schema":{"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","type":"string","minLength":1,"maxLength":64}},{"name":"channel_ids","in":"query","required":false,"description":"Only these channels.","schema":{"description":"Only these channels.","maxItems":50,"type":"array","items":{"type":"string","pattern":"^\\d{1,19}$"}},"style":"form","explode":true,"x-platform-picker":"channels"},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The report.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"range":{"type":"object","properties":{"from":{"type":"string","description":"First local day (YYYY-MM-DD), inclusive."},"to":{"type":"string","description":"Last local day (YYYY-MM-DD), inclusive."},"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of local days in the range."},"timezone":{"type":"string","description":"IANA timezone the days were counted in."},"started_at":{"type":"string","description":"Range start as a UTC instant (ISO-8601)."},"ended_at":{"type":"string","description":"Range end as a UTC instant (ISO-8601), exclusive."},"preset":{"description":"The named range used, if any.","type":["string","null"]}},"required":["from","to","days","timezone","started_at","ended_at","preset"],"additionalProperties":false,"description":"The range and timezone these numbers were counted in — always state it when reporting them."},"totals":{"type":"object","properties":{"closes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Times a conversation was closed in the range (a conversation can be closed more than once)."},"conversations":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Distinct conversations behind those closes."},"with_reason":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"reason_coverage":{"description":"Fraction of closes that recorded a reason (0-1).","type":["number","null"]},"reopen_eligible":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Closes whose reopen window has finished, so the reopen rate can be measured."},"reopened":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"reopen_rate":{"description":"reopened / reopenEligible (0-1); null when nothing is eligible yet.","type":["number","null"]},"median_close_seconds":{"description":"Median time from opening to closing. Null for chunked ranges (medians cannot be merged).","type":["number","null"]},"median_reopen_gap_seconds":{"type":["number","null"]}},"required":["closes","conversations","with_reason","reason_coverage","reopen_eligible","reopened","reopen_rate","median_close_seconds","median_reopen_gap_seconds"],"additionalProperties":false},"previous_period":{"anyOf":[{"type":"object","properties":{"closes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Times a conversation was closed in the range (a conversation can be closed more than once)."},"conversations":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Distinct conversations behind those closes."},"with_reason":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"reason_coverage":{"description":"Fraction of closes that recorded a reason (0-1).","type":["number","null"]},"reopen_eligible":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Closes whose reopen window has finished, so the reopen rate can be measured."},"reopened":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"reopen_rate":{"description":"reopened / reopenEligible (0-1); null when nothing is eligible yet.","type":["number","null"]},"median_close_seconds":{"description":"Median time from opening to closing. Null for chunked ranges (medians cannot be merged).","type":["number","null"]},"median_reopen_gap_seconds":{"type":["number","null"]}},"required":["closes","conversations","with_reason","reason_coverage","reopen_eligible","reopened","reopen_rate","median_close_seconds","median_reopen_gap_seconds"],"additionalProperties":false},{"type":"null"}],"description":"The same length immediately before the range, same filters; null when the platform could not compute it or the range was chunked."},"by_day":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"closes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reopened":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["date","closes","reopened"],"additionalProperties":false}},"by_channel":{"type":"array","items":{"type":"object","properties":{"channel_id":{"type":"string"},"name":{"type":["string","null"]},"type":{"type":["string","null"]},"closes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reopened":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reopen_rate":{"type":["number","null"]}},"required":["channel_id","name","type","closes","reopened","reopen_rate"],"additionalProperties":false}},"top_close_reasons":{"type":"array","items":{"type":"object","properties":{"reason_id":{"type":["string","null"]},"name":{"type":["string","null"]},"closes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"share":{"type":["number","null"]}},"required":["reason_id","name","closes","share"],"additionalProperties":false},"description":"Up to 10, most closes first. reasonId null = closed without a reason."},"waiting_now":{"anyOf":[{"type":"object","properties":{"as_of":{"type":["string","null"]},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"unassigned":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"median_wait_seconds":{"type":["number","null"]},"age":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"description":"Waiting conversations by how long they have been waiting (under_1h, h1_to_4, h4_to_24, d1_to_7, over_7d, unknown)."},"window":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"description":"Waiting conversations by 24-hour WhatsApp reply window (expired, closing_1h, closing_4h, closing_24h, open_over_24h, unknown)."},"stale":{"type":"boolean","description":"true = served from the platform's short cache, not computed this second."}},"required":["as_of","total","unassigned","median_wait_seconds","age","window","stale"],"additionalProperties":false},{"type":"null"}]},"response_times":{"anyOf":[{"type":"object","properties":{"avg_first_response_seconds":{"description":"Assignment → first human reply. A bot reply does not stop this clock.","type":["number","null"]},"avg_time_to_close_seconds":{"type":["number","null"]},"avg_time_to_assignment_seconds":{"description":"Opened → first assignment (queue time). Company-wide only, never per staff.","type":["number","null"]},"from_report":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"from":{"type":"string"},"to":{"type":"string"},"generated_at":{"type":["string","null"]}},"required":["id","name","from","to","generated_at"],"additionalProperties":false}},"required":["avg_first_response_seconds","avg_time_to_close_seconds","avg_time_to_assignment_seconds","from_report"],"additionalProperties":false},{"type":"null"}],"description":"Null when no generated staff report covers this range — ask a manager to generate one in the panel (Analytics → Reports)."},"notes":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string","description":"Which metric or section is missing, e.g. \"messages.read\"."},"reason":{"type":"string","description":"Why it is missing (not supported by this server version, service not configured, forbidden, temporarily unavailable…)."}},"required":["metric","reason"],"additionalProperties":false,"description":"A metric this workspace cannot answer right now. Treat it as unknown — never as zero."},"description":"Metrics that are UNKNOWN (missing data source), not zero. Say so when reporting; do not fill them in with 0."}},"required":["range","totals","previous_period","by_day","by_channel","top_close_reasons","waiting_now","response_times","notes","unavailable"]},"examples":{"week":{"summary":"Last 7 days","value":{"range":{"from":"2026-09-17","to":"2026-09-23","days":7,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"last_7_days"},"totals":{"closes":406,"conversations":398,"reopened":31,"reopen_rate":0.078,"median_close_seconds":5400,"with_reason":null,"reason_coverage":null,"reopen_eligible":null,"median_reopen_gap_seconds":null},"by_day":[{"date":"2026-09-23","closes":61,"reopened":4}],"by_channel":[{"channel_id":"301","name":"Main WhatsApp","closes":380,"reopened":29,"type":null,"reopen_rate":null}],"top_close_reasons":[{"reason_id":"2","name":"Resolved","closes":290,"share":null}],"waiting_now":{"total":9,"unassigned":4,"median_wait_seconds":840,"as_of":null,"age":{},"window":{},"stale":false},"notes":[],"unavailable":[],"previous_period":null,"response_times":null}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"reports_conversations","x-platform-ops-path":"/ops/reports_conversations","x-platform-group":"reports","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"week","summary":"Last 7 days","path":{},"query":{"preset":"last_7_days"},"response":{"status":200,"body":{"range":{"from":"2026-09-17","to":"2026-09-23","days":7,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"last_7_days"},"totals":{"closes":406,"conversations":398,"reopened":31,"reopen_rate":0.078,"median_close_seconds":5400,"with_reason":null,"reason_coverage":null,"reopen_eligible":null,"median_reopen_gap_seconds":null},"by_day":[{"date":"2026-09-23","closes":61,"reopened":4}],"by_channel":[{"channel_id":"301","name":"Main WhatsApp","closes":380,"reopened":29,"type":null,"reopen_rate":null}],"top_close_reasons":[{"reason_id":"2","name":"Resolved","closes":290,"share":null}],"waiting_now":{"total":9,"unassigned":4,"median_wait_seconds":840,"as_of":null,"age":{},"window":{},"stale":false},"notes":[],"unavailable":[],"previous_period":null,"response_times":null}}}]}},"/reports/staff":{"get":{"operationId":"getStaffReport","summary":"Staff report","description":"Per staff member for a period: conversations handled, replies, closes, response and close times, and SLA breaches. Paged with `cursor`.\n\nA metric this workspace cannot answer is `null` and listed in `unavailable[]` with the reason. **Never read `null` as zero.**","tags":["reports"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"preset","in":"query","required":false,"description":"A named period. Default `last_7_days`. Weeks start on Monday.","schema":{"description":"A named period. Default `last_7_days`. Weeks start on Monday.","type":"string","enum":["today","yesterday","last_7_days","last_14_days","last_30_days","this_month","last_month","this_week","last_week"]}},{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","schema":{"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Last day (inclusive), YYYY-MM-DD.","schema":{"description":"Last day (inclusive), YYYY-MM-DD.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"timezone","in":"query","required":false,"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","schema":{"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","type":"string","minLength":1,"maxLength":64}},{"name":"limit","in":"query","required":false,"description":"How many items per page (1–100).","schema":{"default":25,"description":"How many items per page (1–100).","type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","schema":{"description":"The `next_cursor` from the previous page. Cursors expire after 24 hours.","type":"string","minLength":1,"maxLength":2048}},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"A page of staff rows.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"range":{"type":"object","properties":{"from":{"type":"string","description":"First local day (YYYY-MM-DD), inclusive."},"to":{"type":"string","description":"Last local day (YYYY-MM-DD), inclusive."},"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of local days in the range."},"timezone":{"type":"string","description":"IANA timezone the days were counted in."},"started_at":{"type":"string","description":"Range start as a UTC instant (ISO-8601)."},"ended_at":{"type":"string","description":"Range end as a UTC instant (ISO-8601), exclusive."},"preset":{"description":"The named range used, if any.","type":["string","null"]}},"required":["from","to","days","timezone","started_at","ended_at","preset"],"additionalProperties":false,"description":"The range and timezone these numbers were counted in — always state it when reporting them."},"source":{"type":"string","enum":["generated_report","live_closes"],"description":"Where the per-staff numbers come from."},"report":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"from":{"type":"string"},"to":{"type":"string"},"generated_at":{"type":["string","null"]},"timezone":{"type":["string","null"]},"covers_more_than_asked":{"type":"boolean"}},"required":["id","name","from","to","generated_at","timezone","covers_more_than_asked"],"additionalProperties":false},{"type":"null"}],"description":"The generated report used, if any. `coversMoreThanAsked` = its period is wider than the range you asked for, so the numbers cover more days."},"data":{"type":"array","items":{"type":"object","properties":{"staff_id":{"description":"null = unassigned / system.","type":["string","null"]},"name":{"type":["string","null"]},"conversations":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Conversation episodes attributed to this staff member in the range."},"handled":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Episodes they actually held (assignment ledger), not just were assigned at the end."},"closed":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"replied":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"untouched":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Episodes that never got a reply from them."},"messages_sent":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"avg_first_response_seconds":{"description":"Assignment → their first human reply (a bot reply does not stop the clock).","type":["number","null"]},"avg_time_to_close_seconds":{"type":["number","null"]},"reopened":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"sla_breaches":{"anyOf":[{"type":"object","properties":{"first_response":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"next_response":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"resolution":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["first_response","next_response","resolution","total"],"additionalProperties":false},{"type":"null"}],"description":"Null when the source cannot say (live fallback, or SLA not configured)."},"sla_compliance_rate":{"description":"Met / (met + breached) over resolved clocks, 0-1. Not comparable with the per-policy compliance rate.","type":["number","null"]},"reason_coverage":{"description":"Live source only: fraction of their closes that recorded a reason.","type":["number","null"]}},"required":["staff_id","name","conversations","handled","closed","replied","untouched","messages_sent","avg_first_response_seconds","avg_time_to_close_seconds","reopened","sla_breaches","sla_compliance_rate","reason_coverage"],"additionalProperties":false}},"population":{"type":"object","properties":{"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"capped":{"type":"boolean"},"note":{"type":["string","null"]}},"required":["total","capped","note"],"additionalProperties":false,"description":"How many staff the source ranked, and whether it cut the list."},"workload_now":{"type":"array","items":{"type":"object","properties":{"staff_id":{"type":["string","null"]},"name":{"type":["string","null"]},"waiting":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"oldest_wait_seconds":{"type":["number","null"]},"assigned_open":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"window_expired":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["staff_id","name","waiting","oldest_wait_seconds","assigned_open","window_expired"],"additionalProperties":false},"description":"Live snapshot, most waiting first. Empty when unavailable."},"notes":{"type":"array","items":{"type":"string"}},"next_cursor":{"type":["string","null"]},"unavailable":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string","description":"Which metric or section is missing, e.g. \"messages.read\"."},"reason":{"type":"string","description":"Why it is missing (not supported by this server version, service not configured, forbidden, temporarily unavailable…)."}},"required":["metric","reason"],"additionalProperties":false,"description":"A metric this workspace cannot answer right now. Treat it as unknown — never as zero."},"description":"Metrics that are UNKNOWN (missing data source), not zero. Say so when reporting; do not fill them in with 0."}},"required":["range","source","report","data","population","workload_now","notes","next_cursor","unavailable"]},"examples":{"week":{"summary":"Last 7 days","value":{"data":[{"staff_id":"1203","name":"Priya Nair","conversations":120,"closed":98,"replied":410,"avg_first_response_seconds":95,"avg_time_to_close_seconds":5200,"sla_breaches":null,"handled":null,"untouched":null,"messages_sent":null,"reopened":null,"sla_compliance_rate":null,"reason_coverage":null}],"next_cursor":null,"range":{"from":"2026-09-17","to":"2026-09-23","days":7,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"last_7_days"},"unavailable":[],"source":"generated_report","report":null,"population":{"total":null,"capped":false,"note":null},"workload_now":[],"notes":[]}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The key owner has no report permission. `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The key owner has no report permission.","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The key owner has no report permission.","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"reports_staff","x-platform-ops-path":"/ops/reports_staff","x-platform-group":"reports","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The key owner has no report permission."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"week","summary":"Last 7 days","path":{},"query":{},"response":{"status":200,"body":{"data":[{"staff_id":"1203","name":"Priya Nair","conversations":120,"closed":98,"replied":410,"avg_first_response_seconds":95,"avg_time_to_close_seconds":5200,"sla_breaches":null,"handled":null,"untouched":null,"messages_sent":null,"reopened":null,"sla_compliance_rate":null,"reason_coverage":null}],"next_cursor":null,"range":{"from":"2026-09-17","to":"2026-09-23","days":7,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"last_7_days"},"unavailable":[],"source":"generated_report","report":null,"population":{"total":null,"capped":false,"note":null},"workload_now":[],"notes":[]}}}]}},"/reports/sla":{"get":{"operationId":"getSlaReport","summary":"SLA report","description":"SLA breaches in a period by metric (first response, next response, resolution), by day and by staff member. Needs a key made by someone with report permission.\n\nA metric this workspace cannot answer is `null` and listed in `unavailable[]` with the reason. **Never read `null` as zero.**","tags":["reports"],"security":[{"api_key":["mcp:read"]}],"parameters":[{"name":"preset","in":"query","required":false,"description":"A named period. Default `last_7_days`. Weeks start on Monday.","schema":{"description":"A named period. Default `last_7_days`. Weeks start on Monday.","type":"string","enum":["today","yesterday","last_7_days","last_14_days","last_30_days","this_month","last_month","this_week","last_week"]}},{"name":"from","in":"query","required":false,"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","schema":{"description":"First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Last day (inclusive), YYYY-MM-DD.","schema":{"description":"Last day (inclusive), YYYY-MM-DD.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"timezone","in":"query","required":false,"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","schema":{"description":"IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.","type":"string","minLength":1,"maxLength":64}},{"name":"metric_types","in":"query","required":false,"description":"Only these metrics.","schema":{"description":"Only these metrics.","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["FIRST_RESPONSE","NEXT_RESPONSE","RESOLUTION"]}},"style":"form","explode":true},{"$ref":"#/components/parameters/Api-Version"}],"responses":{"200":{"description":"The report.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"range":{"type":"object","properties":{"from":{"type":"string","description":"First local day (YYYY-MM-DD), inclusive."},"to":{"type":"string","description":"Last local day (YYYY-MM-DD), inclusive."},"days":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of local days in the range."},"timezone":{"type":"string","description":"IANA timezone the days were counted in."},"started_at":{"type":"string","description":"Range start as a UTC instant (ISO-8601)."},"ended_at":{"type":"string","description":"Range end as a UTC instant (ISO-8601), exclusive."},"preset":{"description":"The named range used, if any.","type":["string","null"]}},"required":["from","to","days","timezone","started_at","ended_at","preset"],"additionalProperties":false,"description":"The range and timezone these numbers were counted in — always state it when reporting them."},"sla_running":{"description":"Is SLA actually running for this workspace (plan entitlement AND the module switch)? null = unknown.","type":["boolean","null"]},"totals":{"type":"object","properties":{"breaches":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"All breaches in the range (The platform's own count, even when the row scan was capped)."},"by_metric":{"type":"object","properties":{"first_response":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"next_response":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"resolution":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["first_response","next_response","resolution","total"],"additionalProperties":false},"unresolved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Breaches whose clock had still not been satisfied when scanned."},"acknowledged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"avg_breach_seconds":{"description":"Average working-time lateness across the scanned breaches.","type":["number","null"]},"compliance_rate":{"type":"null","description":"Always null here: \"met\" counts exist only inside a generated staff report."}},"required":["breaches","by_metric","unresolved","acknowledged","avg_breach_seconds","compliance_rate"],"additionalProperties":false},"by_policy":{"type":"array","items":{"type":"object","properties":{"policy_id":{"type":["string","null"]},"name":{"type":["string","null"]},"active":{"type":["boolean","null"]},"breaches":{"type":"object","properties":{"first_response":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"next_response":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"resolution":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["first_response","next_response","resolution","total"],"additionalProperties":false}},"required":["policy_id","name","active","breaches"],"additionalProperties":false},"description":"Most breaches first. policyId null = no policy recorded on the breach."},"by_day":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"breaches":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["date","breaches"],"additionalProperties":false},"description":"Breaches per day, keyed on the day the platform rendered the breach time in."},"worst_offenders":{"type":"array","items":{"type":"object","properties":{"staff_id":{"description":"null = nobody was assigned when the clock stopped.","type":["string","null"]},"name":{"type":["string","null"]},"breaches":{"type":"object","properties":{"first_response":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"next_response":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"resolution":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["first_response","next_response","resolution","total"],"additionalProperties":false},"avg_breach_seconds":{"description":"Average working-time lateness of their breaches.","type":["number","null"]},"unresolved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["staff_id","name","breaches","avg_breach_seconds","unresolved"],"additionalProperties":false}},"config_problems":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"fix_hint":{"type":"string"}},"required":["severity","code","message","fix_hint"],"additionalProperties":false},"description":"Why SLA timers do or do not run (from the platform's SLA diagnosis)."},"scanned":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Breach rows read to build the groupings."},"truncated":{"type":"boolean","description":"true = the row scan hit its cap or the time budget; groupings cover only the rows scanned (totals.breaches is still the platform's full count)."},"notes":{"type":"array","items":{"type":"string"}},"unavailable":{"type":"array","items":{"type":"object","properties":{"metric":{"type":"string","description":"Which metric or section is missing, e.g. \"messages.read\"."},"reason":{"type":"string","description":"Why it is missing (not supported by this server version, service not configured, forbidden, temporarily unavailable…)."}},"required":["metric","reason"],"additionalProperties":false,"description":"A metric this workspace cannot answer right now. Treat it as unknown — never as zero."},"description":"Metrics that are UNKNOWN (missing data source), not zero. Say so when reporting; do not fill them in with 0."}},"required":["range","sla_running","totals","by_policy","by_day","worst_offenders","config_problems","scanned","truncated","notes","unavailable"]},"examples":{"week":{"summary":"Last 7 days","value":{"range":{"from":"2026-09-17","to":"2026-09-23","days":7,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"last_7_days"},"sla_running":true,"totals":{"breaches":7,"unresolved":1,"by_metric":{"first_response":-9007199254740991,"next_response":-9007199254740991,"resolution":-9007199254740991,"total":-9007199254740991},"acknowledged":-9007199254740991,"avg_breach_seconds":null,"compliance_rate":null},"by_day":[{"date":"2026-09-23","breaches":2}],"worst_offenders":[{"staff_id":"1203","name":"Priya Nair","breaches":{"first_response":-9007199254740991,"next_response":-9007199254740991,"resolution":-9007199254740991,"total":-9007199254740991},"avg_breach_seconds":null,"unresolved":-9007199254740991}],"notes":[],"unavailable":[],"by_policy":[],"config_problems":[],"scanned":-9007199254740991,"truncated":false}}}}}},"400":{"description":"`invalid_input`: A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_input":{"summary":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","value":{"type":"https://dev.wa-api.cloud/errors/invalid_input","title":"The request is not valid","status":400,"detail":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.","code":"invalid_input","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"401":{"description":"`unauthenticated`: The Authorization header is missing, the key is unknown, expired or revoked.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthenticated":{"summary":"The Authorization header is missing, the key is unknown, expired or revoked.","value":{"type":"https://dev.wa-api.cloud/errors/unauthenticated","title":"No valid API key","status":401,"detail":"The Authorization header is missing, the key is unknown, expired or revoked.","code":"unauthenticated","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"403":{"description":"`entitlement_required`: The workspace's plan does not include API access (`api_access`). `forbidden`: The key owner has no report permission. `insufficient_scope`: The key does not have the permission this operation needs.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"entitlement_required":{"summary":"The workspace's plan does not include API access (`api_access`).","value":{"type":"https://dev.wa-api.cloud/errors/entitlement_required","title":"Not included in your plan","status":403,"detail":"The workspace's plan does not include API access (`api_access`).","code":"entitlement_required","request_id":"req_01J8ZEXAMPLE0000000000000"}},"forbidden":{"summary":"The key owner has no report permission.","value":{"type":"https://dev.wa-api.cloud/errors/forbidden","title":"Not allowed","status":403,"detail":"The key owner has no report permission.","code":"forbidden","request_id":"req_01J8ZEXAMPLE0000000000000"}},"insufficient_scope":{"summary":"The key does not have the permission this operation needs.","value":{"type":"https://dev.wa-api.cloud/errors/insufficient_scope","title":"The key is missing a permission","status":403,"detail":"The key does not have the permission this operation needs.","code":"insufficient_scope","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"429":{"description":"`rate_limited`: The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","value":{"type":"https://dev.wa-api.cloud/errors/rate_limited","title":"Too many requests","status":429,"detail":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds.","code":"rate_limited","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}},"503":{"description":"`upstream_unavailable`: A service behind the API is briefly unavailable. Safe to retry with backoff.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_unavailable":{"summary":"A service behind the API is briefly unavailable. Safe to retry with backoff.","value":{"type":"https://dev.wa-api.cloud/errors/upstream_unavailable","title":"A connected service is unavailable","status":503,"detail":"A service behind the API is briefly unavailable. Safe to retry with backoff.","code":"upstream_unavailable","request_id":"req_01J8ZEXAMPLE0000000000000"}}}}}}},"x-platform-tool":"reports_sla","x-platform-ops-path":"/ops/reports_sla","x-platform-group":"reports","x-platform-scope":"mcp:read","x-platform-plan-feature":"api_access","x-platform-stability":"beta","x-platform-since":"2026-10-01","x-platform-rate-limit":{"class":"read","per_minute":300,"burst":300},"x-platform-idempotency":"none","x-platform-dry-run":null,"x-platform-destructive-verb":null,"x-platform-undo":"Nothing to undo: this only reads.","x-platform-events":[],"x-platform-errors":[{"code":"invalid_input","status":400,"when":"A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown."},{"code":"unauthenticated","status":401,"when":"The Authorization header is missing, the key is unknown, expired or revoked."},{"code":"entitlement_required","status":403,"when":"The workspace's plan does not include API access (`api_access`)."},{"code":"forbidden","status":403,"when":"The key owner has no report permission."},{"code":"insufficient_scope","status":403,"when":"The key does not have the permission this operation needs."},{"code":"rate_limited","status":429,"when":"The key or workspace went over its rate limit. Wait for `Retry-After` seconds."},{"code":"upstream_unavailable","status":503,"when":"A service behind the API is briefly unavailable. Safe to retry with backoff."}],"x-platform-examples":[{"name":"week","summary":"Last 7 days","path":{},"query":{},"response":{"status":200,"body":{"range":{"from":"2026-09-17","to":"2026-09-23","days":7,"timezone":"Asia/Dubai","started_at":"2026-09-16T20:00:00Z","ended_at":"2026-09-23T20:00:00Z","preset":"last_7_days"},"sla_running":true,"totals":{"breaches":7,"unresolved":1,"by_metric":{"first_response":-9007199254740991,"next_response":-9007199254740991,"resolution":-9007199254740991,"total":-9007199254740991},"acknowledged":-9007199254740991,"avg_breach_seconds":null,"compliance_rate":null},"by_day":[{"date":"2026-09-23","breaches":2}],"worst_offenders":[{"staff_id":"1203","name":"Priya Nair","breaches":{"first_response":-9007199254740991,"next_response":-9007199254740991,"resolution":-9007199254740991,"total":-9007199254740991},"avg_breach_seconds":null,"unresolved":-9007199254740991}],"notes":[],"unavailable":[],"by_policy":[],"config_problems":[],"scanned":-9007199254740991,"truncated":false}}}]}}},"components":{"securitySchemes":{"api_key":{"type":"http","scheme":"bearer","bearerFormat":"ak_live_… or ak_test_…","description":"An API key, sent as `Authorization: Bearer <key>`. Test keys (`ak_test_…`) work on your real account but never change anything."}},"parameters":{"Api-Version":{"name":"Api-Version","in":"header","required":false,"description":"The API version to use, e.g. `2026-10-01`. Default: the version your key is pinned to.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","enum":["2026-10-01"]}},"Idempotency-Key":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string (8–128 characters). A retry with the same key returns the first answer instead of running twice. Kept 24 hours.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}},"Idempotency-Key-Required":{"name":"Idempotency-Key","in":"header","required":true,"description":"Required here. Any unique string (8–128 characters), e.g. your order id plus the step. Kept 24 hours. Not needed with `dry_run=true`.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}},"Api-Confirm":{"name":"Api-Confirm","in":"header","required":true,"description":"Type the operation's verb (e.g. `delete`, `submit`) to confirm a change that cannot be undone or that WhatsApp or your customers see. Not needed with `dry_run=true`.","schema":{"type":"string"}},"dry_run":{"name":"dry_run","in":"query","required":false,"description":"Run every check and return a preview, but change nothing. Test keys always run like this.","schema":{"type":"boolean","default":false}},"Webhook-Signature":{"name":"Webhook-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"t.body\">`. Two `v1` values during a secret rotation.","schema":{"type":"string"}},"Webhook-Id":{"name":"Webhook-Id","in":"header","required":true,"description":"The event id; the same on every retry and replay. Use it to skip duplicates.","schema":{"type":"string"}},"Webhook-Event-Id":{"name":"Webhook-Event-Id","in":"header","required":true,"description":"The same value as Webhook-Id.","schema":{"type":"string"}},"Webhook-Delivery-Id":{"name":"Webhook-Delivery-Id","in":"header","required":true,"description":"This delivery attempt; new on every try.","schema":{"type":"string"}}},"headers":{"Request-Id":{"description":"Quote this when you contact support.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window of each limit, the one that will refuse you first coming first, e.g. `\"key\";r=299;t=1, \"workspace\";r=1190;t=1`. `platform` (and `platform_writes` on changes) counts the operations the platform runs for your key: a request can use more than one.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"The limits that apply, in the same order, e.g. `\"key\";q=300;w=60, \"workspace\";q=1200;w=60, \"platform\";q=300;w=60`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"Idempotent-Replayed":{"description":"`true` when this is the stored answer to an earlier request with the same Idempotency-Key.","schema":{"type":"string","enum":["true"]}}},"schemas":{"Problem":{"type":"object","properties":{"type":{"type":"string","description":"A URL that explains this error code.","format":"uri"},"title":{"type":"string","description":"A short, human summary."},"status":{"type":"integer","description":"The HTTP status."},"detail":{"type":"string","description":"What went wrong and how to fix it."},"code":{"type":"string","description":"Stable machine-readable code. Branch on this, not on `title`."},"request_id":{"type":"string","description":"Quote this when you contact support."},"errors":{"type":"array","items":{"type":"object","properties":{"pointer":{"type":"string","description":"JSON pointer to the field, e.g. `/phone`."},"detail":{"type":"string","description":"What is wrong with it."}},"required":["pointer","detail"],"additionalProperties":false},"description":"One entry per invalid field."},"reason":{"type":"string","description":"A finer reason for some codes (e.g. `send_cap`, `burst`)."},"retry_after":{"type":"integer","description":"Seconds to wait before retrying (rate limits only)."},"window":{"type":"string","description":"Send caps: the window that is full (`hour`, `day`, `contact_day`)."},"choices":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"An ambiguous request (`reason` `channel_ambiguous`, `contact_ambiguous`): the candidates to choose from."},"contact_id":{"type":"string","description":"The contact the refusal is about, when your next call needs it (e.g. a closed reply window: send a template to this contact)."},"conversation_id":{"type":"string","description":"The conversation the refusal is about."}},"required":["type","title","status","code","request_id"],"additionalProperties":true}}},"x-platform-rate-limits":{"read":{"class":"read","per_minute":300,"burst":300},"write":{"class":"write","per_minute":60,"burst":60},"workspace_per_minute":1200},"webhooks":{"contact.created/1":{"post":{"operationId":"event_contact_created_v1","summary":"Contact created","description":"A new contact was added — in the app, by an import, or through the API.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"contact.created","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Contact id."},"company_id":{"type":"integer","description":"Workspace id."},"name":{"type":["string","null"],"description":"Name."},"phone_number":{"type":["string","null"],"description":"Phone, digits only."},"custom_identifier":{"type":["string","null"],"description":"Your own id, if set."},"source":{"type":["string","null"],"enum":["manual","api","import",null],"description":"How it was created."},"created_at":{"type":["string","null"],"description":"ISO 8601."},"updated_at":{"type":["string","null"],"description":"ISO 8601."}},"required":["id","company_id"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"contact.created","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":48213,"company_id":1001,"name":"Jane Doe","phone_number":"15555550123","custom_identifier":null,"source":"api","created_at":"2026-09-23T03:02:10Z","updated_at":"2026-09-23T03:02:10Z"}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"contact.created/1","name":"contact.created","version":1,"category":"contacts"}}},"contact.updated/1":{"post":{"operationId":"event_contact_updated_v1","summary":"Contact updated","description":"A contact changed. `changed_fields` lists which fields (names only).","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"contact.updated","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Contact id."},"company_id":{"type":"integer","description":"Workspace id."},"name":{"type":["string","null"],"description":"Name."},"phone_number":{"type":["string","null"],"description":"Phone, digits only."},"custom_identifier":{"type":["string","null"],"description":"Your own id, if set."},"source":{"type":["string","null"],"enum":["manual","api","import",null],"description":"How it was created."},"created_at":{"type":["string","null"],"description":"ISO 8601."},"updated_at":{"type":["string","null"],"description":"ISO 8601."},"changed_fields":{"type":"array","items":{"type":"string"},"description":"Changed field names."}},"required":["id","company_id","changed_fields"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"contact.updated","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":48213,"company_id":1001,"name":"Jane Doe","phone_number":"15555550123","custom_identifier":null,"source":"api","created_at":"2026-09-23T03:02:10Z","updated_at":"2026-09-23T03:02:10Z","changed_fields":["name"]}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"contact.updated/1","name":"contact.updated","version":1,"category":"contacts"}}},"contact.deleted/1":{"post":{"operationId":"event_contact_deleted_v1","summary":"Contact deleted","description":"A contact was deleted.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"contact.deleted","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Contact id."},"company_id":{"type":"integer","description":"Workspace id."},"name":{"type":["string","null"],"description":"Name."},"phone_number":{"type":["string","null"],"description":"Phone, digits only."},"custom_identifier":{"type":["string","null"],"description":"Your own id, if set."},"source":{"type":["string","null"],"enum":["manual","api","import",null],"description":"How it was created."},"created_at":{"type":["string","null"],"description":"ISO 8601."},"updated_at":{"type":["string","null"],"description":"ISO 8601."}},"required":["id","company_id"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"contact.deleted","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":48213,"company_id":1001,"name":"Jane Doe","phone_number":"15555550123","custom_identifier":null,"source":"api","created_at":"2026-09-23T03:02:10Z","updated_at":"2026-09-23T03:02:10Z"}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"contact.deleted/1","name":"contact.deleted","version":1,"category":"contacts"}}},"contact.custom_field.updated/1":{"post":{"operationId":"event_contact_custom_field_updated_v1","summary":"Contact field changed","description":"One custom field value of a contact changed.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"contact.custom_field.updated","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"integer","description":"Contact id."}},"required":["id"],"additionalProperties":false},"field":{"type":"object","properties":{"id":{"type":"integer","description":"Field id."},"label":{"type":["string","null"],"description":"Label."},"name":{"type":"string","description":"Key."},"type":{"type":"string","description":"Type."},"value":{"description":"New value."}},"required":["id","name","type"],"additionalProperties":false},"changed":{"type":"boolean","description":"False when the same value was written again."}},"required":["contact","field","changed"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"contact.custom_field.updated","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"contact":{"id":48213},"field":{"id":12,"label":"Orders","name":"order_count","type":"number","value":5},"changed":true}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"contact.custom_field.updated/1","name":"contact.custom_field.updated","version":1,"category":"contacts"}}},"contact.group.added/1":{"post":{"operationId":"event_contact_group_added_v1","summary":"Contact added to a group","description":"A contact joined a contact group.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"contact.group.added","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},"group":{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false}},"required":["contact","group"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"contact.group.added","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"contact":{"id":48213,"name":"Jane Doe"},"group":{"id":5,"name":"Newsletter"}}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"contact.group.added/1","name":"contact.group.added","version":1,"category":"contacts"}}},"contact.group.removed/1":{"post":{"operationId":"event_contact_group_removed_v1","summary":"Contact removed from a group","description":"A contact left a contact group.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"contact.group.removed","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},"group":{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false}},"required":["contact","group"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"contact.group.removed","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"contact":{"id":48213,"name":"Jane Doe"},"group":{"id":5,"name":"Newsletter"}}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"contact.group.removed/1","name":"contact.group.removed","version":1,"category":"contacts"}}},"contact.import.completed/1":{"post":{"operationId":"event_contact_import_completed_v1","summary":"Contact import finished","description":"A bulk import finished, with its totals.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"contact.import.completed","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"batch_id":{"type":["string","null"],"description":"Import id."},"file_name":{"type":["string","null"],"description":"File name, for file imports."},"totals":{"type":"object","properties":{"created":{"type":"integer","description":"Created."},"failed":{"type":"integer","description":"Failed."},"processed":{"type":"integer","description":"Processed."},"updated":{"type":"integer","description":"Updated."}},"required":["created","failed","processed","updated"],"additionalProperties":false},"started_at":{"type":["string","null"],"description":"ISO 8601."},"finished_at":{"type":["string","null"],"description":"ISO 8601."}},"required":["totals"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"contact.import.completed","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"batch_id":"imp_2211","file_name":null,"totals":{"created":820,"failed":3,"processed":1000,"updated":177},"started_at":"2026-09-23T01:00:00Z","finished_at":"2026-09-23T01:01:12Z"}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"contact.import.completed/1","name":"contact.import.completed","version":1,"category":"contacts"}}},"conversation.created/1":{"post":{"operationId":"event_conversation_created_v1","summary":"Conversation started","description":"A new conversation was opened (usually the first message from a customer).","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"conversation.created","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The contact."},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The channel."},"assigned_staff":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Assigned staff member."},"assigned_team":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Assigned team."},"assigned_at":{"type":["string","null"],"description":"ISO 8601."},"created_at":{"type":["string","null"],"description":"ISO 8601."}},"required":["id","company_id"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"conversation.created","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":77410,"company_id":1001,"contact":{"id":48213,"name":"Jane Doe"},"channel":{"id":301,"name":"Main WhatsApp"},"assigned_staff":null,"assigned_team":null,"assigned_at":null,"created_at":"2026-09-24T09:11:40Z"}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"conversation.created/1","name":"conversation.created","version":1,"category":"conversations"}}},"conversation.assigned/1":{"post":{"operationId":"event_conversation_assigned_v1","summary":"Conversation assigned","description":"A conversation was assigned to a staff member or a team.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"conversation.assigned","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The contact."},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The channel."},"assigned_staff":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Assigned staff member."},"assigned_team":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Assigned team."},"assigned_at":{"type":["string","null"],"description":"ISO 8601."},"created_at":{"type":["string","null"],"description":"ISO 8601."},"previous_staff":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who had it before."},"assignment_type":{"type":"string","enum":["manual","self","auto","team"],"description":"How it was assigned."},"actor":{"anyOf":[{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Id."},"name":{"type":["string","null"],"description":"Name."},"type":{"type":"string","description":"staff, bot, system or api."}},"required":["type"],"additionalProperties":false},{"type":"null"}],"description":"Who did it."}},"required":["id","company_id","assignment_type"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"conversation.assigned","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":77410,"company_id":1001,"contact":{"id":48213,"name":"Jane Doe"},"channel":{"id":301,"name":"Main WhatsApp"},"assigned_staff":{"id":1203,"name":"Priya Nair"},"assigned_team":null,"assigned_at":"2026-09-24T09:13:00Z","created_at":"2026-09-24T09:11:40Z","previous_staff":null,"assignment_type":"manual","actor":{"id":null,"name":null,"type":"api"}}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"conversation.assigned/1","name":"conversation.assigned","version":1,"category":"conversations"}}},"conversation.unassigned/1":{"post":{"operationId":"event_conversation_unassigned_v1","summary":"Conversation unassigned","description":"A conversation went back to the unassigned queue.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"conversation.unassigned","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The contact."},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The channel."},"assigned_staff":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Assigned staff member."},"assigned_team":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Assigned team."},"assigned_at":{"type":["string","null"],"description":"ISO 8601."},"created_at":{"type":["string","null"],"description":"ISO 8601."},"previous_staff":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who had it."},"actor":{"anyOf":[{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Id."},"name":{"type":["string","null"],"description":"Name."},"type":{"type":"string","description":"staff, bot, system or api."}},"required":["type"],"additionalProperties":false},{"type":"null"}],"description":"Who did it."},"reason":{"type":"string","description":"Why."}},"required":["id","company_id","reason"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"conversation.unassigned","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":77410,"company_id":1001,"contact":{"id":48213,"name":"Jane Doe"},"channel":{"id":301,"name":"Main WhatsApp"},"assigned_staff":null,"assigned_team":null,"assigned_at":null,"created_at":"2026-09-24T09:11:40Z","previous_staff":{"id":1203,"name":"Priya Nair"},"actor":{"id":1203,"name":"Priya Nair","type":"staff"},"reason":"manual"}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"conversation.unassigned/1","name":"conversation.unassigned","version":1,"category":"conversations"}}},"conversation.closed/1":{"post":{"operationId":"event_conversation_closed_v1","summary":"Conversation closed","description":"A conversation was closed. A new customer message reopens it.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"conversation.closed","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The contact."},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The channel."},"assigned_staff":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Assigned staff member."},"assigned_team":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Assigned team."},"assigned_at":{"type":["string","null"],"description":"ISO 8601."},"created_at":{"type":["string","null"],"description":"ISO 8601."},"closed_reason":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The close reason."},"actor":{"anyOf":[{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Id."},"name":{"type":["string","null"],"description":"Name."},"type":{"type":"string","description":"staff, bot, system or api."}},"required":["type"],"additionalProperties":false},{"type":"null"}],"description":"Who did it."}},"required":["id","company_id"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"conversation.closed","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":77410,"company_id":1001,"contact":{"id":48213,"name":"Jane Doe"},"channel":{"id":301,"name":"Main WhatsApp"},"assigned_staff":null,"assigned_team":null,"assigned_at":null,"created_at":"2026-09-24T09:11:40Z","closed_reason":{"id":2,"name":"Resolved"},"actor":{"id":1203,"name":"Priya Nair","type":"staff"}}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"conversation.closed/1","name":"conversation.closed","version":1,"category":"conversations"}}},"conversation.reopened/1":{"post":{"operationId":"event_conversation_reopened_v1","summary":"Conversation reopened","description":"A closed conversation was opened again.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"conversation.reopened","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."},"state":{"type":"string","const":"open","description":"Always open."},"channel_id":{"type":"integer","description":"Channel id."},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The contact."},"actor":{"anyOf":[{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Id."},"name":{"type":["string","null"],"description":"Name."},"type":{"type":"string","description":"staff, bot, system or api."}},"required":["type"],"additionalProperties":false},{"type":"null"}],"description":"Who did it."}},"required":["id","company_id","state","channel_id"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"conversation.reopened","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":77410,"company_id":1001,"state":"open","channel_id":301,"contact":{"id":48213,"name":"Jane Doe"},"actor":null}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"conversation.reopened/1","name":"conversation.reopened","version":1,"category":"conversations"}}},"conversation.note.created/1":{"post":{"operationId":"event_conversation_note_created_v1","summary":"Internal note added","description":"A staff member (or the API) added an internal note. Notes are never shown to the customer.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"conversation.note.created","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Note id."},"conversation":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."}},"required":["id","company_id"],"additionalProperties":false},"staff":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who wrote it."},"body":{"type":"string","description":"The note text."},"created_at":{"type":["string","null"],"description":"ISO 8601."}},"required":["id","conversation","body"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"conversation.note.created","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":90331,"conversation":{"id":77410,"company_id":1001},"staff":{"id":1203,"name":"Priya Nair"},"body":"Customer asked for a refund; ticket #4411.","created_at":"2026-09-24T09:20:00Z"}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"conversation.note.created/1","name":"conversation.note.created","version":1,"category":"conversations"}}},"conversation.mention.created/1":{"post":{"operationId":"event_conversation_mention_created_v1","summary":"Staff member mentioned","description":"A staff member was @-mentioned in a conversation (in the app, or by a note with mentions through the API). One event per person mentioned. The note text is not included.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"conversation.mention.created","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Mention id."},"conversation":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."}},"required":["id","company_id"],"additionalProperties":false},"by_staff":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who mentioned them."},"mentioned_staff":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who was mentioned."},"acknowledged_at":{"type":["string","null"],"description":"ISO 8601; null until they acknowledge it."}},"required":["id","conversation","mentioned_staff"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"conversation.mention.created","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":778899,"conversation":{"id":77410,"company_id":1001},"by_staff":{"id":1204,"name":"Daniel Park"},"mentioned_staff":{"id":1203,"name":"Priya Nair"},"acknowledged_at":null}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"conversation.mention.created/1","name":"conversation.mention.created","version":1,"category":"conversations"}}},"conversation.tag.added/1":{"post":{"operationId":"event_conversation_tag_added_v1","summary":"Conversation tagged","description":"A tag was added to a conversation.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"conversation.tag.added","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"conversation":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."}},"required":["id","company_id"],"additionalProperties":false},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The contact."},"tag":{"type":"object","properties":{"id":{"type":"integer","description":"Tag id."},"name":{"type":"string","description":"Name."},"slug":{"type":["string","null"],"description":"Slug."}},"required":["id","name"],"additionalProperties":false}},"required":["conversation","tag"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"conversation.tag.added","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"conversation":{"id":77410,"company_id":1001},"contact":{"id":48213,"name":"Jane Doe"},"tag":{"id":4,"name":"new-lead","slug":"new-lead"}}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"conversation.tag.added/1","name":"conversation.tag.added","version":1,"category":"conversations"}}},"conversation.tag.removed/1":{"post":{"operationId":"event_conversation_tag_removed_v1","summary":"Conversation tag removed","description":"A tag was removed from a conversation.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"conversation.tag.removed","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"conversation":{"type":"object","properties":{"id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."}},"required":["id","company_id"],"additionalProperties":false},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The contact."},"tag":{"type":"object","properties":{"id":{"type":"integer","description":"Tag id."},"name":{"type":"string","description":"Name."},"slug":{"type":["string","null"],"description":"Slug."}},"required":["id","name"],"additionalProperties":false}},"required":["conversation","tag"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"conversation.tag.removed","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"conversation":{"id":77410,"company_id":1001},"contact":{"id":48213,"name":"Jane Doe"},"tag":{"id":4,"name":"new-lead","slug":"new-lead"}}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"conversation.tag.removed/1","name":"conversation.tag.removed","version":1,"category":"conversations"}}},"message.created/1":{"post":{"operationId":"event_message_created_v1","summary":"Message received","description":"A customer sent a message. Use it to react to replies such as STOP. Version 1 covers messages from customers only: messages your team, bots or broadcasts send, reactions and system messages do not fire it.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"message.created","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Message id."},"company_id":{"type":"integer","description":"Workspace id."},"conversation_id":{"type":"integer","description":"Conversation id."},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The contact."},"channel":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The channel."},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Always `inbound` in version 1 (from the customer)."},"type":{"type":"string","description":"TEXT, IMAGE, INTERACTIVE, …"},"text":{"type":["string","null"],"description":"The text, the title of a button or list reply, or a media caption. At most 4096 bytes; media links are never included."},"created_at":{"type":"string","description":"ISO 8601, e.g. 2026-09-24T11:02:00+00:00."}},"required":["id","company_id","conversation_id","direction","type","created_at"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"message.created","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":5501299,"company_id":1001,"conversation_id":77410,"contact":{"id":48213,"name":"Jane Doe"},"channel":{"id":301,"name":"Main WhatsApp"},"direction":"inbound","type":"TEXT","text":"STOP","created_at":"2026-09-24T11:02:00+00:00"}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"message.created/1","name":"message.created","version":1,"category":"messages"}}},"broadcast.created/1":{"post":{"operationId":"event_broadcast_created_v1","summary":"Broadcast created","description":"A broadcast was created in the app.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"broadcast.created","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Broadcast id."},"company_id":{"type":"integer","description":"Workspace id."},"channel_id":{"type":"integer","description":"Channel id."},"name":{"type":["string","null"],"description":"Name."},"status":{"type":"string","description":"Status."},"scheduled_at":{"type":["string","null"],"description":"ISO 8601."},"totals":{"type":"object","properties":{"failed":{"type":"integer","description":"Failed."},"recipients":{"type":"integer","description":"Recipients."},"sent":{"type":"integer","description":"Sent."}},"required":["failed","recipients","sent"],"additionalProperties":false}},"required":["id","company_id","channel_id","status","totals"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"broadcast.created","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":8812,"company_id":1001,"channel_id":301,"name":"September sale","status":"SCHEDULED","scheduled_at":"2026-09-15T07:00:00Z","totals":{"failed":0,"recipients":5300,"sent":0}}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"broadcast.created/1","name":"broadcast.created","version":1,"category":"broadcasts"}}},"tag.created/1":{"post":{"operationId":"event_tag_created_v1","summary":"Tag created","description":"A contact or conversation tag was created.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"tag.created","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Tag id."},"company_id":{"type":"integer","description":"Workspace id."},"name":{"type":["string","null"],"description":"Name."},"slug":{"type":["string","null"],"description":"Slug."},"type":{"type":["string","null"],"description":"contact or conversation."}},"required":["id","company_id"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"tag.created","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"id":17,"company_id":1001,"name":"vip","slug":"vip","type":"contact"}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"tag.created/1","name":"tag.created","version":1,"category":"taxonomy"}}},"sla.warning/1":{"post":{"operationId":"event_sla_warning_v1","summary":"SLA about to breach","description":"An SLA clock is close to its due time.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"sla.warning","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"breach_id":{"type":["integer","null"],"description":"Breach id."},"conversation_id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."},"metric":{"type":"string","enum":["first_response","next_response","resolution"],"description":"Which clock."},"due_at":{"type":"string","description":"When it was due."},"owner":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who owed the clock."},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The contact."},"seconds_to_due":{"type":["integer","null"],"description":"Business seconds left."}},"required":["conversation_id","company_id","metric","due_at"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"sla.warning","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"breach_id":551,"conversation_id":77410,"company_id":1001,"metric":"first_response","due_at":"2026-09-24T09:26:40Z","owner":{"id":1203,"name":"Priya Nair"},"contact":{"id":48213,"name":"Jane Doe"},"seconds_to_due":120}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"sla.warning/1","name":"sla.warning","version":1,"category":"sla"}}},"sla.breached/2":{"post":{"operationId":"event_sla_breached_v2","summary":"SLA breached","description":"An SLA clock went past its due time.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"sla.breached","description":"Event type."},"version":{"type":"string","const":"2","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"breach_id":{"type":["integer","null"],"description":"Breach id."},"conversation_id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."},"metric":{"type":"string","enum":["first_response","next_response","resolution"],"description":"Which clock."},"due_at":{"type":"string","description":"When it was due."},"owner":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who owed the clock."},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The contact."},"breached_at":{"type":"string","description":"ISO 8601."},"late_seconds":{"type":["integer","null"],"description":"How late, in seconds."}},"required":["conversation_id","company_id","metric","due_at","breached_at"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"sla.breached","version":"2","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"breach_id":551,"conversation_id":77410,"company_id":1001,"metric":"first_response","due_at":"2026-09-24T09:26:40Z","owner":{"id":1203,"name":"Priya Nair"},"contact":{"id":48213,"name":"Jane Doe"},"breached_at":"2026-09-24T09:26:41Z","late_seconds":0}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"sla.breached/2","name":"sla.breached","version":2,"category":"sla"}}},"sla.met/1":{"post":{"operationId":"event_sla_met_v1","summary":"SLA met","description":"A reply or close stopped an SLA clock in time.","tags":["events"],"parameters":[{"$ref":"#/components/parameters/Webhook-Signature"},{"$ref":"#/components/parameters/Webhook-Id"},{"$ref":"#/components/parameters/Webhook-Event-Id"},{"$ref":"#/components/parameters/Webhook-Delivery-Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","version","api_version","occurred_at","company_id","data"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$","description":"Event id. The same on every retry: use it to skip duplicates."},"type":{"type":"string","const":"sla.met","description":"Event type."},"version":{"type":"string","const":"1","description":"Payload version."},"api_version":{"type":"string","description":"The endpoint's API version."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened."},"company_id":{"type":"integer","description":"Your workspace id."},"data":{"type":"object","properties":{"breach_id":{"type":["integer","null"],"description":"Breach id."},"conversation_id":{"type":"integer","description":"Conversation id."},"company_id":{"type":"integer","description":"Workspace id."},"metric":{"type":"string","enum":["first_response","next_response","resolution"],"description":"Which clock."},"due_at":{"type":"string","description":"When it was due."},"owner":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who owed the clock."},"contact":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"The contact."},"met_at":{"type":"string","description":"ISO 8601."},"met_by":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Id."},"name":{"type":["string","null"],"description":"Name."}},"required":["id","name"],"additionalProperties":false},{"type":"null"}],"description":"Who met it."},"seconds_before_due":{"type":["integer","null"],"description":"Business seconds to spare."}},"required":["conversation_id","company_id","metric","due_at","met_at"],"additionalProperties":false}}},"example":{"id":"evt_01J8Z7BZQ4F6G8J2K5N7Q9S1VC","type":"sla.met","version":"1","api_version":"2026-10-01","occurred_at":"2026-09-24T09:20:00Z","company_id":1001,"data":{"breach_id":551,"conversation_id":77410,"company_id":1001,"metric":"first_response","due_at":"2026-09-24T09:26:40Z","owner":{"id":1203,"name":"Priya Nair"},"contact":{"id":48213,"name":"Jane Doe"},"met_at":"2026-09-24T09:20:00Z","met_by":{"id":1203,"name":"Priya Nair"},"seconds_before_due":400}}}}},"responses":{"2XX":{"description":"Answer any 2xx within 30 seconds. Anything else is retried (4xx is not)."}},"x-platform-event":{"id":"sla.met/1","name":"sla.met","version":1,"category":"sla"}}}}}