{ "openapi": "3.1.0", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "info": { "title": "Zono Support REST API", "version": "1.1.0", "summary": "Tickets, customers, conversations and webhooks for Zono Support teams (Premium).", "description": "Authenticate with an OAuth 2.0 access token (authorization code flow, PKCE required for public clients; see the `oauth2` security scheme) or a team API key (Profile > API & MCP tokens), either one sent as `Authorization: Bearer `. Each token carries scopes (tickets:read, tickets:write, customers:read, customers:write, conversations:read, conversations:write, knowledge:read, licenses:read, webhooks:manage), chosen when the key was created or approved on the OAuth consent screen; every operation names the scopes that allow it in `x-zono-scopes`, and a token without one of them gets a 403 naming the missing scope. The API acts as the token's user, for the one team the token names.\n\nLists use cursor pagination: pass `per_page` (1-100, default 25) and follow `meta.next_cursor` as `?cursor=...` until it is null. Timestamps are ISO-8601 in UTC. Fields are only ever added to v1, never renamed or removed.\n\nWebhooks are described under `webhooks`: every delivery is a signed POST with the same envelope. No-code tools subscribe through the Webhook subscriptions endpoints (REST Hooks).\n\nHuman-readable reference: https://zono.support/developers/api", "contact": { "name": "Zono Support", "url": "https://zono.support/developers/api" } }, "servers": [ { "url": "https://zono.support/api/v1", "description": "REST API v1" } ], "security": [ { "bearerAuth": [] }, { "oauth2": [] } ], "tags": [ { "name": "Account", "description": "Check which user, team and access a token has." }, { "name": "Tickets", "description": "Changes run through the same code as the app: notifications, SLA clocks, automation rules and webhooks all fire." }, { "name": "Customers", "description": "Admin and owner tokens only, as in the app: other roles get 403. Email addresses and external ids are unique per team. Passwords and tokens are never accepted or returned. Changing an email clears its verification, so the customer must verify the new address before using the portal." }, { "name": "Licenses", "description": "Purchase codes and license keys stored for the team's customers, and live checks against the marketplace. Admin and owner tokens only, as they reveal customer data. Verifying never stores or changes anything, so a read-only token is enough." }, { "name": "Conversations", "description": "Inbox conversations from every channel, limited to what the token's user sees in the Inbox, and what an agent does there: reply or add an internal note, assign, resolve, reopen, mark as spam, mark read and show a live chat visitor they are typing. Changes behave exactly as in the Inbox: a promoted conversation is replied to, assigned, closed and reopened through its ticket." }, { "name": "Reference data", "description": "Read-only lists to map names to the ids tickets use." }, { "name": "Knowledge base", "description": "Articles (read only). Admin and owner tokens also see drafts; other roles see published articles only." }, { "name": "Webhook subscriptions", "description": "REST Hooks for no-code tools (Zapier, n8n, Make): subscribe a URL to events when a trigger is switched on and unsubscribe when it is switched off. Deliveries are signed and retried like any webhook. Owner and admin tokens only (other roles get 403); subscriptions belong to the token (an API key, or the OAuth app's connection), so revoking the key or disconnecting the app removes them. Endpoints added under Settings > Webhooks are not listed here and cannot be changed through the API." } ], "paths": { "/conversations": { "get": { "operationId": "conversationsIndex", "summary": "List conversations", "description": "List conversations, newest first unless sorted. Each carries whether the token's user has unread messages on it and a preview of its latest public message.", "tags": [ "Conversations" ], "x-zono-ability": "read", "x-zono-scopes": [ "conversations:read" ], "x-zono-route": "api.v1.conversations.index", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "open, resolved or abandoned.", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "description": "email, livechat, slack, discord, whatsapp, instagram, telegram, messenger, line, tiktok or ai_agent.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Customer id.", "schema": { "type": "string" } }, { "name": "assignee", "in": "query", "required": false, "description": "me (the conversation or its ticket is assigned to the token's user) or unassigned.", "schema": { "type": "string" } }, { "name": "unread", "in": "query", "required": false, "description": "1 or true: only conversations with messages the token's user has not read.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "-created_at, -last_message_at (default -created_at). -last_message_at puts the latest activity first.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/conversations/{conversation}": { "get": { "operationId": "conversationsShow", "summary": "Get a conversation", "description": "One conversation with its channel, customer and ticket.", "tags": [ "Conversations" ], "x-zono-ability": "read", "x-zono-scopes": [ "conversations:read" ], "x-zono-route": "api.v1.conversations.show", "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "conversationsUpdate", "summary": "Update a conversation", "description": "Assign or unassign, resolve or reopen the conversation. Send at least one field. Resolving a live chat ends it in the visitor's widget (with the rating prompt when CSAT is on); outside live chat a promoted conversation's ticket is closed or reopened with it. Reopening answers 422 when the customer already has another open conversation on the channel.", "tags": [ "Conversations" ], "x-zono-ability": "write", "x-zono-scopes": [ "conversations:write" ], "x-zono-route": "api.v1.conversations.update", "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "open or resolved." }, "assignee_id": { "type": [ "string", "null" ], "description": "A team member, or null to unassign. A promoted conversation is assigned through its ticket." }, "close_reason": { "type": [ "string", "null" ], "description": "With status resolved: resolved, not_resolved or spam, kept on the ticket the conversation closes (as on Update a ticket). Ignored for a conversation that is not a ticket." }, "close_reason_detail": { "type": [ "string", "null" ], "description": "With close_reason not_resolved: duplicate, no_reply, out_of_scope." } } }, "example": { "status": "resolved" } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/conversations/{conversation}/messages": { "get": { "operationId": "conversationsMessagesIndex", "summary": "List a conversation's messages", "description": "The conversation's messages, oldest first unless sorted, internal notes included.", "tags": [ "Conversations" ], "x-zono-ability": "read", "x-zono-scopes": [ "conversations:read" ], "x-zono-route": "api.v1.conversations.messages.index", "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "created_at (oldest first, default) or -created_at (newest first).", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "conversationsMessagesStore", "summary": "Reply to a conversation", "description": "Reply as the token's user, exactly as in the Inbox: the customer gets it on the conversation's channel (live chat: instantly in the widget). A promoted conversation's reply is written on its ticket. Marks the conversation read for the token's user.", "tags": [ "Conversations" ], "x-zono-ability": "write", "x-zono-scopes": [ "conversations:write" ], "x-zono-route": "api.v1.conversations.messages.store", "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "The reply, up to 10,000 characters; HTML or plain text." }, "internal": { "type": "boolean", "description": "An internal note the customer never sees (default false)." } }, "required": [ "body" ] }, "example": { "body": "Thanks Ada, I have reset your activation." } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/conversations/{conversation}/metadata": { "patch": { "operationId": "conversationsMetadataUpdate", "summary": "Set a conversation's metadata", "description": "Set metadata about the conversation, shown to your team under From your app, and on the ticket if it is promoted. Keys are 1 to 40 lowercase letters, digits and underscores (zono_ is reserved; keys naming passwords, secrets, tokens, cards, CVV, SSN or IBAN are refused). Values are strings of at most 255 characters (ISO dates as strings), numbers or booleans; null deletes the key. At most 30 keys are kept and 4 KB sent per request; the latest write of a key wins. Strings that look like a card number or an IBAN are stored as [removed]. Values written here are marked Signed in the inbox and are never sent to the AI agent.", "tags": [ "Conversations" ], "x-zono-ability": "write", "x-zono-scopes": [ "conversations:write" ], "x-zono-route": "api.v1.conversations.metadata.update", "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": true, "description": "Keys and values to set; null removes a key." } }, "required": [ "metadata" ] }, "example": { "metadata": { "order_id": "A-1042", "cart_total": 59.9 } } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/conversations/{conversation}/read": { "post": { "operationId": "conversationsRead", "summary": "Mark a conversation read", "description": "Mark the conversation read for the token's user. Answers 204.", "tags": [ "Conversations" ], "x-zono-ability": "read", "x-zono-scopes": [ "conversations:read" ], "x-zono-route": "api.v1.conversations.read", "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/conversations/{conversation}/spam": { "post": { "operationId": "conversationsSpamStore", "summary": "Mark a conversation as spam", "description": "Mark the conversation as spam, as the Inbox does: a promoted conversation through its ticket (see Mark a ticket as spam); a chat that is not a ticket is resolved and needs block. The conversation's spam field turns true.", "tags": [ "Conversations" ], "x-zono-ability": "write", "x-zono-scopes": [ "conversations:write" ], "x-zono-route": "api.v1.conversations.spam.store", "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "block": { "type": "array", "items": { "type": "string" }, "description": "Also block the sender by any of: email, domain (not free email providers), ip (live chat visitors), customer. Types the sender has no value for are skipped and listed in meta.skipped." }, "include_other_open": { "type": "boolean", "description": "Also mark the customer's other open tickets (those you can access) as spam." } } }, "example": { "block": [ "email", "ip" ] } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "conversationsSpamDestroy", "summary": "Move a conversation out of spam", "description": "Move the conversation's ticket out of spam. Answers 409 when it is not marked as spam.", "tags": [ "Conversations" ], "x-zono-ability": "write", "x-zono-scopes": [ "conversations:write" ], "x-zono-route": "api.v1.conversations.spam.destroy", "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "remove_blocks": { "type": "boolean", "description": "Also lift the blocks that match the sender. Owners and admins only (403 otherwise)." } } } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/conversations/{conversation}/typing": { "post": { "operationId": "conversationsTyping", "summary": "Show the visitor you are typing", "description": "Show the live chat visitor that the token's user is typing; send it every few seconds while they type. Other channels have no typing indicator: nothing happens. Answers 204.", "tags": [ "Conversations" ], "x-zono-ability": "write", "x-zono-scopes": [ "conversations:write" ], "x-zono-route": "api.v1.conversations.typing", "parameters": [ { "name": "conversation", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/customers": { "get": { "operationId": "customersIndex", "summary": "List customers", "description": "List customers, newest first.", "tags": [ "Customers" ], "x-zono-ability": "read", "x-zono-scopes": [ "customers:read" ], "x-zono-route": "api.v1.customers.index", "parameters": [ { "name": "email", "in": "query", "required": false, "description": "Exact email (case-insensitive).", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "required": false, "description": "Your own id for the customer.", "schema": { "type": "string" } }, { "name": "marketplace_username", "in": "query", "required": false, "description": "The customer's username on a connected marketplace, e.g. their Envato buyer username (case-insensitive).", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Matches name or email.", "schema": { "type": "string" } }, { "name": "updated_after", "in": "query", "required": false, "description": "ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "customersStore", "summary": "Create a customer", "description": "Create a customer. The email is marked verified: your team vouches for it.", "tags": [ "Customers" ], "x-zono-ability": "write", "x-zono-scopes": [ "customers:write" ], "x-zono-route": "api.v1.customers.store", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Unique in the team." }, "name": { "type": "string", "description": "Defaults to the part of the email before @." }, "external_id": { "type": "string", "description": "Your own id for the customer; unique in the team." } }, "required": [ "email" ] }, "example": { "email": "ada@example.com", "name": "Ada Lovelace", "external_id": "crm-5521" } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/customers/{customer}": { "get": { "operationId": "customersShow", "summary": "Get a customer", "description": "One customer.", "tags": [ "Customers" ], "x-zono-ability": "read", "x-zono-scopes": [ "customers:read" ], "x-zono-route": "api.v1.customers.show", "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "customersUpdate", "summary": "Update a customer", "description": "Change a customer's name, email or external id.", "tags": [ "Customers" ], "x-zono-ability": "write", "x-zono-scopes": [ "customers:write" ], "x-zono-route": "api.v1.customers.update", "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Unique in the team." }, "name": { "type": "string", "description": "Display name." }, "external_id": { "type": [ "string", "null" ], "description": "Your own id for the customer." } } }, "example": { "name": "Ada King" } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/customers/{customer}/attributes": { "patch": { "operationId": "customersAttributesUpdate", "summary": "Set a customer's attributes", "description": "Set details about the customer, shown to your team under Sent by your website. Keys are 1 to 40 lowercase letters, digits and underscores (zono_ is reserved; keys naming passwords, secrets, tokens, cards, CVV, SSN or IBAN are refused). Values are strings of at most 255 characters (ISO dates as strings), numbers or booleans; null deletes the key. At most 30 keys are kept and 4 KB sent per request; the latest write of a key wins. Strings that look like a card number or an IBAN are stored as [removed]. Values written here are marked Signed in the inbox and are never sent to the AI agent.", "tags": [ "Customers" ], "x-zono-ability": "write", "x-zono-scopes": [ "customers:write" ], "x-zono-route": "api.v1.customers.attributes.update", "parameters": [ { "name": "customer", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attributes": { "type": "object", "additionalProperties": true, "description": "Keys and values to set; null removes a key." } }, "required": [ "attributes" ] }, "example": { "attributes": { "plan": "pro", "seats": 12 } } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAttributes" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/departments": { "get": { "operationId": "departmentsIndex", "summary": "List departments", "description": "Departments.", "tags": [ "Reference data" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read", "customers:read", "conversations:read", "knowledge:read", "licenses:read" ], "x-zono-route": "api.v1.departments.index", "parameters": [ { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Department" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/departments/{department}": { "get": { "operationId": "departmentsShow", "summary": "Get a department", "description": "One department.", "tags": [ "Reference data" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read", "customers:read", "conversations:read", "knowledge:read", "licenses:read" ], "x-zono-route": "api.v1.departments.show", "parameters": [ { "name": "department", "in": "path", "required": true, "description": "Department id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Department" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/hooks": { "get": { "operationId": "hooksIndex", "summary": "List webhook subscriptions", "description": "The team's API subscriptions, newest first. Secrets are never returned.", "tags": [ "Webhook subscriptions" ], "x-zono-ability": "read", "x-zono-scopes": [ "webhooks:manage" ], "x-zono-route": "api.v1.hooks.index", "parameters": [ { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "hooksStore", "summary": "Subscribe to webhook events", "description": "Subscribe a URL to one or more events. The response carries the signing secret, once.", "tags": [ "Webhook subscriptions" ], "x-zono-ability": "write", "x-zono-scopes": [ "webhooks:manage" ], "x-zono-route": "api.v1.hooks.store", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_url": { "type": "string", "description": "Public https URL to POST events to (url is accepted too)." }, "event": { "type": "string", "description": "One event, e.g. ticket.created. Required unless events is given." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Several events, or [\"*\"] for all." }, "description": { "type": "string", "description": "Shown in Settings > Webhooks, e.g. the Zap name." }, "integration": { "type": "string", "description": "zapier, n8n, make or other (shown as a badge in Settings)." } }, "required": [ "target_url" ] }, "example": { "target_url": "https://hooks.zapier.com/hooks/standard/123/abc", "event": "ticket.created", "integration": "zapier" } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/hooks/samples/{event}": { "get": { "operationId": "hooksSamples", "summary": "Get sample event payloads", "description": "Up to 3 sample payloads for an event, exactly as delivered: the team's latest real events, else one built from its latest matching record (data.sample = true), else a static example.", "tags": [ "Webhook subscriptions" ], "x-zono-ability": "read", "x-zono-scopes": [ "webhooks:manage" ], "x-zono-route": "api.v1.hooks.samples", "parameters": [ { "name": "event", "in": "path", "required": true, "description": "A subscribable event, e.g. ticket.created.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEnvelope" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/hooks/{hook}": { "get": { "operationId": "hooksShow", "summary": "Get a webhook subscription", "description": "One API subscription.", "tags": [ "Webhook subscriptions" ], "x-zono-ability": "read", "x-zono-scopes": [ "webhooks:manage" ], "x-zono-route": "api.v1.hooks.show", "parameters": [ { "name": "hook", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "hooksDestroy", "summary": "Unsubscribe", "description": "Unsubscribe. Answers 204, or 404 if the subscription is gone.", "tags": [ "Webhook subscriptions" ], "x-zono-ability": "write", "x-zono-scopes": [ "webhooks:manage" ], "x-zono-route": "api.v1.hooks.destroy", "parameters": [ { "name": "hook", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Done; no content." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/knowledge-base/articles": { "get": { "operationId": "knowledgeBaseArticlesIndex", "summary": "List knowledge base articles", "description": "List articles, most recently updated first.", "tags": [ "Knowledge base" ], "x-zono-ability": "read", "x-zono-scopes": [ "knowledge:read" ], "x-zono-route": "api.v1.knowledge-base.articles.index", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "published or draft (draft: admin and owner tokens only).", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "required": false, "description": "Category id.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Matches the title.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/knowledge-base/articles/{article}": { "get": { "operationId": "knowledgeBaseArticlesShow", "summary": "Get a knowledge base article", "description": "One article by id or slug.", "tags": [ "Knowledge base" ], "x-zono-ability": "read", "x-zono-scopes": [ "knowledge:read" ], "x-zono-route": "api.v1.knowledge-base.articles.show", "parameters": [ { "name": "article", "in": "path", "required": true, "description": "Article id or slug.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/licenses": { "get": { "operationId": "licensesIndex", "summary": "api.v1.licenses.index", "description": "List stored licenses, newest first.", "tags": [ "Licenses" ], "x-zono-ability": "read", "x-zono-scopes": [ "licenses:read" ], "x-zono-route": "api.v1.licenses.index", "parameters": [ { "name": "purchase_code", "in": "query", "required": false, "description": "Exact purchase code or license key, as issued or in all lower or upper case.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Customer id.", "schema": { "type": "string" } }, { "name": "marketplace", "in": "query", "required": false, "description": "envato, shopify, wordpress, gumroad, lemonsqueezy, independent.", "schema": { "type": "string" } }, { "name": "product_id", "in": "query", "required": false, "description": "Product id.", "schema": { "type": "integer" } }, { "name": "external_license_id", "in": "query", "required": false, "description": "The marketplace's own id for the license or order.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/License" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/licenses/verify": { "post": { "operationId": "licensesVerify", "summary": "api.v1.licenses.verify", "description": "Check a key live against the marketplace. Returns valid, a short summary (item, buyer, license type, dates), and the stored license and customer if any. Limited to 30 requests per minute per token.", "tags": [ "Licenses" ], "x-zono-ability": "read", "x-zono-scopes": [ "licenses:read" ], "x-zono-route": "api.v1.licenses.verify", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "license_key": { "type": "string", "description": "The purchase code or license key." }, "product_id": { "type": "integer", "description": "Verify the way this product is set up to (no license, manual or automatic)." }, "marketplace": { "type": "string", "description": "Marketplace to ask when no product is given. Defaults to the stored license's marketplace, then the team's primary one." } }, "required": [ "license_key" ] }, "example": { "license_key": "86781236-23d0-4b3c-7dfa-c1c147e0dece", "marketplace": "envato" } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseVerification" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/me": { "get": { "operationId": "me", "summary": "Get the token's user and team", "description": "The token's user, team and access (read or write).", "tags": [ "Account" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read", "tickets:write", "customers:read", "customers:write", "conversations:read", "conversations:write", "knowledge:read", "licenses:read", "webhooks:manage" ], "x-zono-route": "api.v1.me", "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/products": { "get": { "operationId": "productsIndex", "summary": "List products", "description": "Products.", "tags": [ "Reference data" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read", "customers:read", "conversations:read", "knowledge:read", "licenses:read" ], "x-zono-route": "api.v1.products.index", "parameters": [ { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/products/{product}": { "get": { "operationId": "productsShow", "summary": "Get a product", "description": "One product.", "tags": [ "Reference data" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read", "customers:read", "conversations:read", "knowledge:read", "licenses:read" ], "x-zono-route": "api.v1.products.show", "parameters": [ { "name": "product", "in": "path", "required": true, "description": "Product id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tags": { "get": { "operationId": "tagsIndex", "summary": "List tags", "description": "Ticket tags.", "tags": [ "Reference data" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read", "customers:read", "conversations:read", "knowledge:read", "licenses:read" ], "x-zono-route": "api.v1.tags.index", "parameters": [ { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tags/{tag}": { "get": { "operationId": "tagsShow", "summary": "Get a tag", "description": "One tag.", "tags": [ "Reference data" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read", "customers:read", "conversations:read", "knowledge:read", "licenses:read" ], "x-zono-route": "api.v1.tags.show", "parameters": [ { "name": "tag", "in": "path", "required": true, "description": "Tag id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tickets": { "get": { "operationId": "ticketsIndex", "summary": "List tickets", "description": "List tickets the token's user can see.", "tags": [ "Tickets" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read" ], "x-zono-route": "api.v1.tickets.index", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "open, answered, on-hold or closed; comma-separate several.", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "required": false, "description": "low, normal, high, urgent or none; comma-separate several.", "schema": { "type": "string" } }, { "name": "assignee_id", "in": "query", "required": false, "description": "A user id, \"me\" or \"unassigned\".", "schema": { "type": "string" } }, { "name": "department_id", "in": "query", "required": false, "description": "Department id.", "schema": { "type": "string" } }, { "name": "product_id", "in": "query", "required": false, "description": "Product id.", "schema": { "type": "integer" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Customer id.", "schema": { "type": "string" } }, { "name": "customer_email", "in": "query", "required": false, "description": "The customer's exact email (case-insensitive). Works for every role, still limited to tickets the token's user can see.", "schema": { "type": "string" } }, { "name": "tag_id", "in": "query", "required": false, "description": "Tickets carrying this tag.", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "required": false, "description": "ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "required": false, "description": "ISO-8601 timestamp; use it to sync changes.", "schema": { "type": "string", "format": "date-time" } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive match on the subject; a ticket number (1042 or #1042) also matches that ticket.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "created_at, -created_at, updated_at, -updated_at (default -created_at).", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "ticketsStore", "summary": "Create a ticket", "description": "Create a ticket for an existing customer, or for a customer found (or created) by email.", "tags": [ "Tickets" ], "x-zono-ability": "write", "x-zono-scopes": [ "tickets:write" ], "x-zono-route": "api.v1.tickets.store", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Up to 255 characters." }, "description": { "type": "string", "description": "The first message; HTML is kept." }, "product_id": { "type": "integer", "description": "One of the team's products (GET /products)." }, "customer_id": { "type": "string", "description": "Required unless customer is given." }, "customer": { "type": "object", "additionalProperties": true, "description": "{\"email\", \"name\", \"external_id\"}: found by email or created. Admin and owner tokens that also carry the customers:write scope (others get 403); agents pass customer_id." }, "priority": { "type": "string", "description": "low, normal, high or urgent." }, "department_id": { "type": "string", "description": "Department id." }, "assignee_id": { "type": "string", "description": "A team member who may work the ticket." }, "tag_ids": { "type": "array", "items": { "type": "string" }, "description": "Tag ids (GET /tags)." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Values keyed by field key. Required fields must be set." } }, "required": [ "subject", "description", "product_id" ] }, "example": { "subject": "Cannot activate my license", "description": "My key says it is already in use.", "product_id": 12, "customer": { "email": "ada@example.com", "name": "Ada Lovelace" }, "priority": "high" } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tickets/{ticket}": { "get": { "operationId": "ticketsShow", "summary": "Get a ticket", "description": "One ticket with its customer, assignee, tags, custom fields and SLA summary.", "tags": [ "Tickets" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read" ], "x-zono-route": "api.v1.tickets.show", "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "Ticket ULID or ticket number.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "ticketsUpdate", "summary": "Update a ticket", "description": "Change a ticket. Only the fields you send change. Merged tickets answer 409.", "tags": [ "Tickets" ], "x-zono-ability": "write", "x-zono-scopes": [ "tickets:write" ], "x-zono-route": "api.v1.tickets.update", "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "Ticket ULID or ticket number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "New subject." }, "description": { "type": "string", "description": "New description." }, "status": { "type": "string", "description": "open, answered, on-hold or closed. Closing needs every required custom field." }, "close_reason": { "type": [ "string", "null" ], "description": "With status closed: resolved (the default), not_resolved or spam." }, "close_reason_detail": { "type": [ "string", "null" ], "description": "With close_reason not_resolved: duplicate, no_reply, out_of_scope." }, "priority": { "type": [ "string", "null" ], "description": "low, normal, high, urgent or null." }, "assignee_id": { "type": [ "string", "null" ], "description": "A team member, or null to unassign." }, "department_id": { "type": [ "string", "null" ], "description": "Department id or null." }, "product_id": { "type": "integer", "description": "Product id." }, "tag_ids": { "type": "array", "items": { "type": "string" }, "description": "Replaces the ticket's tags." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Values keyed by field key; null clears an optional field." } } }, "example": { "status": "on-hold", "priority": "urgent", "custom_fields": { "order_number": "A-1042" } } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/MergedTicket" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tickets/{ticket}/metadata": { "patch": { "operationId": "ticketsMetadataUpdate", "summary": "Set a ticket's metadata", "description": "Set metadata about the ticket, shown to your team under From your app. A ticket that came from a chat keeps it on its conversation, so the chat shows the same values. Keys are 1 to 40 lowercase letters, digits and underscores (zono_ is reserved; keys naming passwords, secrets, tokens, cards, CVV, SSN or IBAN are refused). Values are strings of at most 255 characters (ISO dates as strings), numbers or booleans; null deletes the key. At most 30 keys are kept and 4 KB sent per request; the latest write of a key wins. Strings that look like a card number or an IBAN are stored as [removed]. Values written here are marked Signed in the inbox and are never sent to the AI agent.", "tags": [ "Tickets" ], "x-zono-ability": "write", "x-zono-scopes": [ "tickets:write" ], "x-zono-route": "api.v1.tickets.metadata.update", "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "Ticket ULID or ticket number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": true, "description": "Keys and values to set; null removes a key." } }, "required": [ "metadata" ] }, "example": { "metadata": { "order_id": "A-1042", "refund_eligible": true } } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/MergedTicket" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tickets/{ticket}/notes": { "get": { "operationId": "ticketsNotesIndex", "summary": "List a ticket's notes", "description": "The ticket's internal notes, oldest first unless sorted.", "tags": [ "Tickets" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read" ], "x-zono-route": "api.v1.tickets.notes.index", "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "Ticket ULID or ticket number.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "created_at (oldest first, default) or -created_at (newest first).", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "ticketsNotesStore", "summary": "Add a note to a ticket", "description": "Add an internal note as the token's user.", "tags": [ "Tickets" ], "x-zono-ability": "write", "x-zono-scopes": [ "tickets:write" ], "x-zono-route": "api.v1.tickets.notes.store", "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "Ticket ULID or ticket number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "The note." } }, "required": [ "body" ] }, "example": { "body": "Refund approved by finance." } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Note" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/MergedTicket" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tickets/{ticket}/replies": { "get": { "operationId": "ticketsRepliesIndex", "summary": "List a ticket's replies", "description": "The ticket's replies, oldest first unless sorted, internal replies included.", "tags": [ "Tickets" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read" ], "x-zono-route": "api.v1.tickets.replies.index", "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "Ticket ULID or ticket number.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "created_at (oldest first, default) or -created_at (newest first).", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Reply" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "ticketsRepliesStore", "summary": "Reply to a ticket", "description": "Reply as the token's user. Public replies are sent to the customer on the ticket's channel.", "tags": [ "Tickets" ], "x-zono-ability": "write", "x-zono-scopes": [ "tickets:write" ], "x-zono-route": "api.v1.tickets.replies.store", "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "Ticket ULID or ticket number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "The reply; HTML is kept." }, "is_internal": { "type": "boolean", "description": "Staff-only reply (default false)." }, "close_ticket": { "type": "boolean", "description": "Close the ticket with this reply (default false)." } }, "required": [ "body" ] }, "example": { "body": "Thanks Ada, a new key is on its way.", "close_ticket": true } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reply" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/MergedTicket" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tickets/{ticket}/spam": { "post": { "operationId": "ticketsSpamStore", "summary": "Mark a ticket as spam", "description": "Mark the ticket as spam, as the ticket page does: it leaves the app's ticket lists, its SLA clocks and survey stop, and it is deleted for good after 30 days unless moved out of spam (the ticket's spam field shows when). Marking a spam ticket again changes nothing. meta tells how many tickets were marked and what was blocked or skipped. Merged tickets answer 409.", "tags": [ "Tickets" ], "x-zono-ability": "write", "x-zono-scopes": [ "tickets:write" ], "x-zono-route": "api.v1.tickets.spam.store", "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "Ticket ULID or ticket number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "block": { "type": "array", "items": { "type": "string" }, "description": "Also block the sender by any of: email, domain (not free email providers), ip (live chat visitors), customer. Types the sender has no value for are skipped and listed in meta.skipped." }, "include_other_open": { "type": "boolean", "description": "Also mark the customer's other open tickets (those you can access) as spam." } } }, "example": { "block": [ "email" ] } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/MergedTicket" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "ticketsSpamDestroy", "summary": "Move a ticket out of spam", "description": "Move the ticket out of spam: it is back in the app's lists and its SLA clocks resume. meta.unmarked is false when it was not spam.", "tags": [ "Tickets" ], "x-zono-ability": "write", "x-zono-scopes": [ "tickets:write" ], "x-zono-route": "api.v1.tickets.spam.destroy", "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "Ticket ULID or ticket number.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "remove_blocks": { "type": "boolean", "description": "Also lift the blocks that match the sender. Owners and admins only (403 otherwise)." } } }, "example": { "remove_blocks": true } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/MergedTicket" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/users": { "get": { "operationId": "usersIndex", "summary": "List team members", "description": "Team members with their role.", "tags": [ "Reference data" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read" ], "x-zono-route": "api.v1.users.index", "parameters": [ { "name": "per_page", "in": "query", "required": false, "description": "1-100, default 25.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "meta.next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/CursorMeta" } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/users/{user}": { "get": { "operationId": "usersShow", "summary": "Get a team member", "description": "One team member.", "tags": [ "Reference data" ], "x-zono-ability": "read", "x-zono-scopes": [ "tickets:read" ], "x-zono-route": "api.v1.users.show", "parameters": [ { "name": "user", "in": "path", "required": true, "description": "User id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "webhooks": { "ticket.created": { "post": { "operationId": "webhookTicketCreated", "summary": "Ticket created", "description": "A ticket was created by staff, a customer, the API, a channel or a split.", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.created" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "source": { "type": "string", "description": "Where the ticket came from, when known." }, "split_from": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.created", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "source": "api" } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ticket.updated": { "post": { "operationId": "webhookTicketUpdated", "summary": "Ticket updated", "description": "Subject, description, product, priority, department, tags or custom fields changed. `data.changes` lists what changed.", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.updated" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "changes": { "type": "object", "description": "What changed: fields (names), custom_fields (keys), tags ({new}), or a field's {old, new} (priority, department_id).", "additionalProperties": true }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.updated", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "changes": { "priority": { "old": "normal", "new": "high" } } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ticket.status_changed": { "post": { "operationId": "webhookTicketStatusChanged", "summary": "Ticket status changed", "description": "The ticket status changed. `data.changes.status` has the old and new status.", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.status_changed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "changes": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/Change" } }, "required": [ "status" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.status_changed", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "changes": { "status": { "old": "open", "new": "answered" } } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ticket.closed": { "post": { "operationId": "webhookTicketClosed", "summary": "Ticket closed", "description": "The ticket was closed (sent alongside ticket.status_changed).", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.closed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "changes": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/Change" } }, "required": [ "status" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.closed", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "closed", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": "2026-01-15T10:24:07Z", "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "changes": { "status": { "old": "answered", "new": "closed" } } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ticket.assigned": { "post": { "operationId": "webhookTicketAssigned", "summary": "Ticket assigned", "description": "The ticket was assigned, reassigned or unassigned.", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.assigned" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "changes": { "type": "object", "properties": { "assignee_id": { "$ref": "#/components/schemas/Change" } }, "required": [ "assignee_id" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.assigned", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "changes": { "assignee_id": { "old": null, "new": "01j9x0u1v2w3x4y5z6a7b8c9d0" } } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ticket.replied": { "post": { "operationId": "webhookTicketReplied", "summary": "Public reply added", "description": "A public reply was posted by staff, the AI Agent or the customer. `data.reply` holds it.", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.replied" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "reply": { "$ref": "#/components/schemas/Reply" }, "actor": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.replied", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "reply": { "object": "reply", "id": "01j9x3m4k7d2c8b5a6f0e1g2h4", "ticket_id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "body": "

Thanks Ada, a new key is on its way.

", "is_internal": false, "source": "web", "author": { "type": "user", "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent" }, "created_at": "2026-01-15T10:24:07Z" }, "actor": { "type": "staff", "id": "01j9x0u1v2w3x4y5z6a7b8c9d0" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ticket.note_added": { "post": { "operationId": "webhookTicketNoteAdded", "summary": "Internal note added", "description": "An internal note or internal reply was added. `data.note` or `data.reply` holds it.", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.note_added" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "note": { "$ref": "#/components/schemas/Note" }, "reply": { "allOf": [ { "$ref": "#/components/schemas/Reply" } ], "description": "An internal reply (instead of note)." }, "actor": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.note_added", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "note": { "object": "note", "id": "01j9x3n4o5t6e7a8b9c0d1e2f3", "ticket_id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "body": "Refund approved by finance.", "author": { "type": "user", "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent" }, "created_at": "2026-01-15T10:24:07Z", "updated_at": "2026-01-15T10:24:07Z" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ticket.merged": { "post": { "operationId": "webhookTicketMerged", "summary": "Tickets merged", "description": "A ticket was merged into this one. `data.merged_ticket` names the source.", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.merged" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "merged_ticket": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": [ "integer", "null" ] } }, "required": [ "id", "number" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.merged", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "merged_ticket": { "id": "01j9x2p3q4r5s6t7u8v9w0x1y3", "number": 1043 } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ticket.split": { "post": { "operationId": "webhookTicketSplit", "summary": "Ticket split", "description": "Replies were split off into this new ticket. `data.split_from` names the original.", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.split" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "split_from": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": [ "integer", "null" ] } }, "required": [ "id", "number" ] }, "reply_count": { "type": "integer" }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.split", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "split_from": { "id": "01j9x2p3q4r5s6t7u8v9w0x1y1", "number": 1041 }, "reply_count": 2 } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ticket.classified": { "post": { "operationId": "webhookTicketClassified", "summary": "Ticket classified by AI", "description": "AI Triage classified the ticket. `data.triage` has the intent, sentiment, language and confidence.", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.classified" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "triage": { "type": "object", "properties": { "intent": { "type": [ "string", "null" ] }, "sentiment": { "type": [ "string", "null" ] }, "sentiment_score": { "type": [ "number", "null" ] }, "previous_sentiment_score": { "type": [ "number", "null" ] }, "sentiment_trend": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "confidence": { "type": [ "number", "null" ] } }, "required": [ "intent", "sentiment", "sentiment_score", "previous_sentiment_score", "sentiment_trend", "language", "confidence" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.classified", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "triage": { "intent": "licensing", "sentiment": "negative", "sentiment_score": -0.62, "previous_sentiment_score": null, "sentiment_trend": "declining", "language": "en", "confidence": 0.91 } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ticket.sentiment_dropped": { "post": { "operationId": "webhookTicketSentimentDropped", "summary": "Customer sentiment dropped", "description": "AI Triage saw the customer's sentiment drop sharply. `data.triage` has the new and previous sentiment scores.", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.sentiment_dropped" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "triage": { "type": "object", "properties": { "intent": { "type": [ "string", "null" ] }, "sentiment": { "type": [ "string", "null" ] }, "sentiment_score": { "type": [ "number", "null" ] }, "previous_sentiment_score": { "type": [ "number", "null" ] }, "sentiment_trend": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "confidence": { "type": [ "number", "null" ] } }, "required": [ "intent", "sentiment", "sentiment_score", "previous_sentiment_score", "sentiment_trend", "language", "confidence" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.sentiment_dropped", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "triage": { "intent": "licensing", "sentiment": "negative", "sentiment_score": -0.62, "previous_sentiment_score": 0.1, "sentiment_trend": "declining", "language": "en", "confidence": 0.91 } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ticket.linked_issue_status_changed": { "post": { "operationId": "webhookTicketLinkedIssueStatusChanged", "summary": "Linked issue status changed", "description": "A Linear or GitHub issue linked to the ticket changed status. `data.issue` has the provider, identifier, URL and the new and previous status.", "tags": [ "Webhook events: Tickets" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ticket.linked_issue_status_changed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "issue": { "type": "object", "properties": { "provider": { "type": [ "string", "null" ], "enum": [ "linear", "github", null ] }, "identifier": { "type": [ "string", "null" ], "description": "e.g. ENG-123 or owner/repo#42." }, "title": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "open", "in_progress", "done", "canceled", null ] }, "previous_status": { "type": [ "string", "null" ], "enum": [ "open", "in_progress", "done", "canceled", null ] }, "linked_ticket_count": { "type": [ "integer", "null" ], "description": "How many tickets the issue is linked to." } }, "required": [ "provider", "identifier", "title", "url", "status", "previous_status", "linked_ticket_count" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ticket.linked_issue_status_changed", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "issue": { "provider": "linear", "identifier": "ENG-123", "title": "License activation fails for reused keys", "url": "https://linear.app/acme/issue/ENG-123", "status": "done", "previous_status": "in_progress", "linked_ticket_count": 3 } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "customer.created": { "post": { "operationId": "webhookCustomerCreated", "summary": "Customer created", "description": "A customer record was created, from any channel, import or the API.", "tags": [ "Webhook events: Customers" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "customer.created" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Customer" }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "customer.created", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "customer", "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com", "external_id": "crm-5521", "avatar": null, "has_deliverable_email": true, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T09:58:12Z", "url": "https://zono.support/customers/01j9x1c2d3e4f5g6h7j8k9m0n1" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "conversation.promoted": { "post": { "operationId": "webhookConversationPromoted", "summary": "Conversation promoted to a ticket", "description": "An Inbox conversation was promoted to a ticket.", "tags": [ "Webhook events: Conversations" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "conversation.promoted" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Conversation" }, "ticket": { "$ref": "#/components/schemas/Ticket" }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "conversation.promoted", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "conversation", "id": "01j9x4c5d6e7f8g9h0j1k2m3n4", "subject": "Cannot activate my license", "status": "open", "channel": { "id": "01j9x0c1h2a3n4n5e6l7a8b9c0", "type": "whatsapp", "name": "WhatsApp support" }, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": null, "ticket": { "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042 }, "spam": false, "triage": null, "last_message_at": "2026-01-15T09:58:12Z", "created_at": "2026-01-15T09:50:01Z", "updated_at": "2026-01-15T09:58:12Z", "unread": true, "handed_off_at": null, "last_message": { "id": "01j9x4m5s6g7h8j9k0m1n2p3q4", "author_type": "customer", "author_name": "Ada Lovelace", "preview": "My license key says it is already in use on another site.", "created_at": "2026-01-15T09:58:12Z" } }, "ticket": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "csat.rated": { "post": { "operationId": "webhookCsatRated", "summary": "Customer rated support", "description": "A customer answered (or changed) a satisfaction survey. `data.object` is the ticket, or the live chat conversation when the chat never became a ticket; `data.rating` has the score.", "tags": [ "Webhook events: Satisfaction" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "csat.rated" }, "data": { "type": "object", "properties": { "object": { "anyOf": [ { "$ref": "#/components/schemas/Ticket" }, { "$ref": "#/components/schemas/Conversation" } ], "description": "The ticket, or the live chat conversation when the chat never became a ticket." }, "rating": { "$ref": "#/components/schemas/Rating" }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "csat.rated", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "rating": { "score": 5, "previous_score": null, "source": "email", "has_comment": true } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "sla.warning": { "post": { "operationId": "webhookSlaWarning", "summary": "SLA due soon", "description": "An SLA target on the ticket is due soon.", "tags": [ "Webhook events: SLA" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "sla.warning" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "sla": { "type": "object", "properties": { "metric": { "type": [ "string", "null" ], "description": "first_response, next_response or resolution." }, "policy_id": { "type": [ "string", "null" ] } }, "required": [ "metric", "policy_id" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "sla.warning", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "sla": { "metric": "first_response", "policy_id": "01j9x0s1l2a3p4o5l6i7c8y9z0" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "sla.breached": { "post": { "operationId": "webhookSlaBreached", "summary": "SLA breached", "description": "An SLA target on the ticket was missed.", "tags": [ "Webhook events: SLA" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "sla.breached" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "sla": { "type": "object", "properties": { "metric": { "type": [ "string", "null" ], "description": "first_response, next_response or resolution." }, "policy_id": { "type": [ "string", "null" ] } }, "required": [ "metric", "policy_id" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "sla.breached", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "sla": { "metric": "first_response", "policy_id": "01j9x0s1l2a3p4o5l6i7c8y9z0" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "ping": { "post": { "operationId": "webhookPing", "summary": "Test event", "description": "Sent when you click \"Send test event\". Never sent otherwise. (Cannot be subscribed to.)", "tags": [ "Webhook events: Other" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "ping" }, "data": { "type": "object", "properties": { "object": { "type": "object", "properties": { "object": { "type": "string", "const": "ping" }, "message": { "type": "string" }, "endpoint": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url" ] } }, "required": [ "object", "message", "endpoint" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "ping", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ping", "message": "Hello from Zono. Your endpoint received this test event.", "endpoint": { "id": "01j9x5h6o7o8k9s0a1b2c3d4e5", "url": "https://example.com/webhooks/zono" } } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } }, "automation.webhook_called": { "post": { "operationId": "webhookAutomationWebhookCalled", "summary": "Automation rule called this webhook", "description": "Sent by an automation rule's \"Call webhook\" action. `data.rule` names the rule. (Cannot be subscribed to.)", "tags": [ "Webhook events: Other" ], "security": [], "parameters": [ { "name": "Zono-Signature", "in": "header", "required": true, "description": "t=,v1=.\">. During a secret rotation a second v1 value is sent.", "schema": { "type": "string" } }, { "name": "Zono-Event", "in": "header", "required": true, "description": "The event type, e.g. ticket.created.", "schema": { "type": "string" } }, { "name": "Zono-Event-Id", "in": "header", "required": true, "description": "The event id (evt_...). The same on every retry and manual resend: use it to ignore duplicates.", "schema": { "type": "string" } }, { "name": "Zono-Delivery", "in": "header", "required": true, "description": "This delivery's id. Changes on every resend.", "schema": { "type": "string" } }, { "name": "User-Agent", "in": "header", "required": true, "description": "Zono-Webhooks/1.0", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "type": { "type": "string", "const": "automation.webhook_called" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Ticket" }, "rule": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "trigger": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "trigger" ] }, "sample": { "type": "boolean", "description": "Only on samples built for a no-code trigger test." }, "truncated": { "type": "boolean", "description": "Set when the payload was over 256 KB: data.object then only has its id." } }, "required": [ "object" ] } } } ] }, "example": { "id": "evt_01j9x3m4k7d2c8b5a6f0e1g2h3", "type": "automation.webhook_called", "api_version": "v1", "created_at": "2026-01-15T10:24:07Z", "team": { "id": "01j9x0a1b2c3d4e5f6g7h8j9k0" }, "data": { "object": { "object": "ticket", "id": "01j9x2p3q4r5s6t7u8v9w0x1y2", "number": 1042, "subject": "Cannot activate my license", "description": "

My key says it is already in use.

", "status": "answered", "priority": "high", "close_reason": null, "close_reason_detail": null, "customer": { "id": "01j9x1c2d3e4f5g6h7j8k9m0n1", "name": "Ada Lovelace", "email": "ada@example.com" }, "assignee": { "id": "01j9x0u1v2w3x4y5z6a7b8c9d0", "name": "Sam Agent", "email": "sam@yourcompany.com" }, "department": { "id": "01j9x0d1e2p3t4a5b6c7d8e9f0", "name": "Billing" }, "product": { "id": 12, "name": "Zono Desktop" }, "channel": null, "tags": [ { "id": "01j9x0t1a2g3b4c5d6e7f8g9h0", "name": "licensing", "color": "#6366f1" } ], "custom_fields": { "order_number": "A-1042" }, "sla": null, "triage": null, "conversation_id": null, "spam": null, "merged_into": null, "created_at": "2026-01-15T09:58:12Z", "updated_at": "2026-01-15T10:24:07Z", "last_reply_at": "2026-01-15T10:24:07Z", "first_response_at": "2026-01-15T10:24:07Z", "closed_at": null, "url": "https://zono.support/tickets/01j9x2p3q4r5s6t7u8v9w0x1y2" }, "rule": { "id": "01j9x0r1u2l3e4a5b6c7d8e9f0", "name": "Escalate VIP tickets", "trigger": "ticket_created" } } } } } }, "responses": { "2XX": { "description": "Any 2xx status within the timeout acknowledges the delivery; anything else is retried." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A team API key from Profile > API & MCP tokens (Premium), with the scopes chosen when it was created, or an OAuth access token. A request whose token lacks the scope an operation needs (x-zono-scopes) gets a 403 naming the missing scope." }, "oauth2": { "type": "oauth2", "description": "OAuth 2.0 for apps that act for a Zono user, such as automation tools and browser extensions. Access tokens last 60 minutes; refresh tokens rotate on every use and expire after 180 days unused. Public clients register at https://zono.support/oauth/register (RFC 7591) and must use PKCE (S256). Revoke a token at https://zono.support/oauth/revoke (RFC 7009). Discovery: https://zono.support/.well-known/oauth-authorization-server.", "flows": { "authorizationCode": { "authorizationUrl": "https://zono.support/oauth/authorize", "tokenUrl": "https://zono.support/oauth/token", "refreshUrl": "https://zono.support/oauth/token", "scopes": { "tickets:read": "List, search and read tickets, their replies, notes and custom fields.", "tickets:write": "Create tickets, reply, add notes, assign, change status or fields, and merge tickets.", "customers:read": "List and read customers (team owners and admins only).", "customers:write": "Create and update customers (team owners and admins only).", "conversations:read": "Read channel conversations and their messages.", "conversations:write": "Reply to conversations, add internal notes, assign, resolve and reopen them, and show live chat visitors you are typing.", "knowledge:read": "Search the help center and knowledge sources, and ask for cited answers.", "licenses:read": "Look up and verify license keys and purchases.", "webhooks:manage": "Subscribe and unsubscribe webhooks for Zapier, n8n or Make (owners and admins only), for the events the app may read." } } } } }, "schemas": { "CustomerRef": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" } }, "required": [ "id", "name", "email" ] }, "LicenseCustomerRef": { "type": "object", "description": "The customer a license belongs to. Name and email are only included for a token with the customers:read scope.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" } }, "required": [ "id" ] }, "CustomerId": { "type": "object", "description": "A customer named by id only: what a token without customers:read gets.", "properties": { "object": { "type": "string", "const": "customer" }, "id": { "type": "string" } }, "required": [ "object", "id" ] }, "UserRef": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "id", "name", "email" ] }, "NamedRef": { "type": "object", "properties": { "id": { "type": [ "string", "integer" ] }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "ChannelRef": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": [ "string", "null" ], "description": "email, livechat, slack, discord, whatsapp, instagram, telegram, messenger, line, tiktok or ai_agent." }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "name" ] }, "TicketRef": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" } }, "required": [ "id", "number" ] }, "TagRef": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "color" ] }, "Author": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "customer", "ai_agent" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "type", "id", "name" ] }, "Triage": { "type": "object", "description": "What AI Triage detected.", "properties": { "intent": { "type": [ "string", "null" ] }, "sentiment": { "type": [ "string", "null" ] }, "sentiment_score": { "type": [ "number", "null" ] }, "language": { "type": [ "string", "null" ] }, "triaged_at": { "type": [ "string", "null" ], "format": "date-time" }, "sentiment_trend": { "type": [ "string", "null" ], "description": "Tickets only." } }, "required": [ "intent", "sentiment", "sentiment_score", "language", "triaged_at" ] }, "TicketSla": { "type": "object", "description": "The SLA target that is due next; null when SLAs are off or none apply.", "properties": { "policy": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "metric": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "policy", "state", "metric", "due_at" ] }, "TicketSpam": { "type": "object", "description": "Set while the ticket is marked as spam; null otherwise.", "properties": { "marked_at": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ], "enum": [ "manual", "blocked_sender", "honeypot", "too_fast", "provider_score", null ], "description": "manual when an agent marked it." }, "deletes_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "marked_at", "reason", "deletes_at" ] }, "Ticket": { "type": "object", "properties": { "object": { "type": "string", "const": "ticket" }, "id": { "type": "string" }, "number": { "type": "integer" }, "subject": { "type": "string" }, "description": { "type": "string", "description": "HTML." }, "status": { "type": [ "string", "null" ], "enum": [ "open", "answered", "on-hold", "closed", null ] }, "priority": { "type": [ "string", "null" ], "enum": [ "low", "normal", "high", "urgent", null ] }, "close_reason": { "type": [ "string", "null" ], "enum": [ "resolved", "not_resolved", "spam", null ], "description": "Why it was closed, when it was closed with a reason." }, "close_reason_detail": { "type": [ "string", "null" ], "description": "Sub-reason of not_resolved: duplicate, no_reply, out_of_scope." }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/CustomerRef" }, { "type": "null" } ] }, "assignee": { "anyOf": [ { "$ref": "#/components/schemas/UserRef" }, { "type": "null" } ] }, "department": { "anyOf": [ { "$ref": "#/components/schemas/NamedRef" }, { "type": "null" } ] }, "product": { "anyOf": [ { "$ref": "#/components/schemas/NamedRef" }, { "type": "null" } ] }, "channel": { "anyOf": [ { "$ref": "#/components/schemas/ChannelRef" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagRef" } }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Values keyed by field key." }, "sla": { "anyOf": [ { "$ref": "#/components/schemas/TicketSla" }, { "type": "null" } ] }, "triage": { "anyOf": [ { "$ref": "#/components/schemas/Triage" }, { "type": "null" } ] }, "conversation_id": { "type": [ "string", "null" ] }, "spam": { "anyOf": [ { "$ref": "#/components/schemas/TicketSpam" }, { "type": "null" } ] }, "merged_into": { "anyOf": [ { "$ref": "#/components/schemas/TicketRef" }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_reply_at": { "type": [ "string", "null" ], "format": "date-time" }, "first_response_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string", "format": "uri", "description": "The ticket in the Zono app." } }, "required": [ "object", "id", "number", "subject", "description", "status", "priority", "close_reason", "close_reason_detail", "customer", "assignee", "department", "product", "channel", "tags", "custom_fields", "sla", "triage", "conversation_id", "spam", "merged_into", "created_at", "updated_at", "last_reply_at", "first_response_at", "closed_at", "url" ] }, "Reply": { "type": "object", "properties": { "object": { "type": "string", "const": "reply" }, "id": { "type": "string" }, "ticket_id": { "type": "string" }, "body": { "type": "string", "description": "HTML." }, "is_internal": { "type": "boolean" }, "source": { "type": [ "string", "null" ] }, "author": { "anyOf": [ { "$ref": "#/components/schemas/Author" }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "ticket_id", "body", "is_internal", "source", "author", "created_at" ] }, "Note": { "type": "object", "properties": { "object": { "type": "string", "const": "note" }, "id": { "type": "string" }, "ticket_id": { "type": "string" }, "body": { "type": "string" }, "author": { "anyOf": [ { "$ref": "#/components/schemas/Author" }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "ticket_id", "body", "author", "created_at", "updated_at" ] }, "Customer": { "type": "object", "properties": { "object": { "type": "string", "const": "customer" }, "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "external_id": { "type": [ "string", "null" ] }, "avatar": { "type": [ "string", "null" ] }, "has_deliverable_email": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string", "format": "uri", "description": "The customer in the Zono app." } }, "required": [ "object", "id", "name", "email", "external_id", "avatar", "has_deliverable_email", "created_at", "updated_at", "url" ] }, "License": { "type": "object", "properties": { "object": { "type": "string", "const": "license" }, "id": { "type": "string" }, "purchase_code": { "type": [ "string", "null" ] }, "marketplace": { "type": [ "string", "null" ], "enum": [ "envato", "shopify", "wordpress", "gumroad", "lemonsqueezy", "independent", null ] }, "external_license_id": { "type": [ "string", "null" ] }, "product": { "anyOf": [ { "$ref": "#/components/schemas/NamedRef" }, { "type": "null" } ] }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/LicenseCustomerRef" }, { "type": "null" } ] }, "license_type": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "has_active_support": { "type": "boolean" }, "support_status": { "type": [ "string", "null" ] }, "purchase_date": { "type": [ "string", "null" ], "format": "date-time" }, "support_until": { "type": [ "string", "null" ], "format": "date-time" }, "verification_source": { "type": [ "string", "null" ] }, "last_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "purchase_code", "marketplace", "external_license_id", "product", "customer", "license_type", "is_active", "has_active_support", "support_status", "purchase_date", "support_until", "verification_source", "last_verified_at", "created_at" ] }, "LicenseVerification": { "type": "object", "properties": { "object": { "type": "string", "const": "license_verification" }, "valid": { "type": "boolean" }, "error": { "type": [ "string", "null" ], "description": "Why the key is not valid; null when it is." }, "marketplace": { "type": [ "string", "null" ], "enum": [ "envato", "shopify", "wordpress", "gumroad", "lemonsqueezy", "independent", null ] }, "mode": { "type": [ "string", "null" ], "description": "How the key was checked (the product's verification mode)." }, "summary": { "anyOf": [ { "type": "object", "properties": { "item": { "type": [ "string", "null" ] }, "buyer": { "type": [ "string", "null" ] }, "buyer_email": { "type": [ "string", "null" ] }, "license_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "purchased_at": { "type": [ "string", "null" ] }, "supported_until": { "type": [ "string", "null" ] } }, "required": [ "item", "buyer", "buyer_email", "license_type", "status", "purchased_at", "supported_until" ] }, { "type": "null" } ], "description": "What the marketplace reported; only when the key is valid." }, "license": { "anyOf": [ { "$ref": "#/components/schemas/License" }, { "type": "null" } ] }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/Customer" }, { "$ref": "#/components/schemas/CustomerId" }, { "type": "null" } ] } }, "required": [ "object", "valid", "error", "marketplace", "mode", "summary", "license", "customer" ] }, "Conversation": { "type": "object", "properties": { "object": { "type": "string", "const": "conversation" }, "id": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "description": "open, resolved or abandoned." }, "channel": { "anyOf": [ { "$ref": "#/components/schemas/ChannelRef" }, { "type": "null" } ] }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/CustomerRef" }, { "type": "null" } ] }, "assignee": { "anyOf": [ { "$ref": "#/components/schemas/UserRef" }, { "type": "null" } ] }, "ticket": { "anyOf": [ { "$ref": "#/components/schemas/TicketRef" }, { "type": "null" } ] }, "spam": { "type": "boolean", "description": "Whether the conversation's ticket is marked as spam." }, "triage": { "anyOf": [ { "$ref": "#/components/schemas/Triage" }, { "type": "null" } ] }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "unread": { "type": [ "boolean", "null" ], "description": "Whether the token's user has messages to catch up on: they never read the conversation, or a message came after they last did. Null in webhook payloads, which have no reader." }, "handed_off_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_message": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "author_type": { "type": "string", "enum": [ "customer", "agent", "ai" ] }, "author_name": { "type": [ "string", "null" ] }, "preview": { "type": "string", "description": "Plain text, at most 140 characters." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "author_type", "author_name", "preview", "created_at" ] }, { "type": "null" } ], "description": "The latest message the customer can see (internal notes left out)." } }, "required": [ "object", "id", "subject", "status", "channel", "customer", "assignee", "ticket", "spam", "triage", "last_message_at", "created_at", "updated_at", "unread", "handed_off_at", "last_message" ] }, "Message": { "type": "object", "properties": { "object": { "type": "string", "const": "message" }, "id": { "type": "string" }, "conversation_id": { "type": "string" }, "body": { "type": "string" }, "is_internal": { "type": "boolean" }, "source": { "type": [ "string", "null" ] }, "author": { "anyOf": [ { "$ref": "#/components/schemas/Author" }, { "type": "null" } ] }, "author_type": { "type": "string", "enum": [ "customer", "agent", "ai" ], "description": "customer, ai (the AI Agent) or agent (anyone else on the team's side)." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "mime_type": { "type": [ "string", "null" ] }, "size": { "type": "integer" } }, "required": [ "name", "url", "mime_type", "size" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "conversation_id", "body", "is_internal", "source", "author", "author_type", "attachments", "created_at" ] }, "MetadataValues": { "type": "object", "description": "Key => {value, signed, via, updated_at}. signed is true for values written by your server; via says how: api (this API) or token (a metadata token signed with the identity secret), null for values set from the browser.", "additionalProperties": { "type": "object", "properties": { "value": { "type": [ "string", "number", "boolean" ] }, "signed": { "type": "boolean" }, "via": { "type": [ "string", "null" ], "enum": [ "api", "token", null ] }, "updated_at": { "type": "string" } }, "required": [ "value", "signed", "via", "updated_at" ] } }, "Metadata": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation", "ticket" ] }, "id": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/MetadataValues" } }, "required": [ "object", "id", "metadata" ] }, "CustomerAttributes": { "type": "object", "properties": { "object": { "type": "string", "const": "customer" }, "id": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/MetadataValues" } }, "required": [ "object", "id", "attributes" ] }, "Tag": { "type": "object", "properties": { "object": { "type": "string", "const": "tag" }, "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "name", "slug", "color", "created_at" ] }, "Department": { "type": "object", "properties": { "object": { "type": "string", "const": "department" }, "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "name", "description", "active", "created_at" ] }, "Product": { "type": "object", "properties": { "object": { "type": "string", "const": "product" }, "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "marketplace": { "type": [ "string", "null" ] }, "external_product_id": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "name", "description", "active", "marketplace", "external_product_id", "url", "created_at" ] }, "User": { "type": "object", "properties": { "object": { "type": "string", "const": "user" }, "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "avatar": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ], "description": "owner, admin or agent." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "name", "email", "avatar", "role", "created_at" ] }, "Article": { "type": "object", "properties": { "object": { "type": "string", "const": "knowledge_base_article" }, "id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "content": { "type": "string", "description": "HTML." }, "status": { "type": "string", "enum": [ "published", "draft" ] }, "privacy": { "type": [ "string", "null" ] }, "is_featured": { "type": "boolean" }, "category": { "anyOf": [ { "$ref": "#/components/schemas/NamedRef" }, { "type": "null" } ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "title", "slug", "excerpt", "content", "status", "privacy", "is_featured", "category", "published_at", "created_at", "updated_at" ] }, "Me": { "type": "object", "properties": { "object": { "type": "string", "const": "token" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role" ] }, "team": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "token": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "access": { "type": "string", "enum": [ "read", "write" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "tickets:read", "tickets:write", "customers:read", "customers:write", "conversations:read", "conversations:write", "knowledge:read", "licenses:read", "webhooks:manage" ] }, "description": "The scopes the token grants (see Authentication)." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "allowed_ips": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "access", "scopes", "expires_at", "allowed_ips" ] }, { "type": "null" } ] } }, "required": [ "object", "user", "team", "token" ] }, "WebhookSubscription": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_subscription" }, "id": { "type": "string" }, "target_url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "ticket.created", "ticket.updated", "ticket.status_changed", "ticket.closed", "ticket.assigned", "ticket.replied", "ticket.note_added", "ticket.merged", "ticket.split", "ticket.classified", "ticket.sentiment_dropped", "ticket.linked_issue_status_changed", "customer.created", "conversation.promoted", "csat.rated", "sla.warning", "sla.breached" ] } }, "description": { "type": [ "string", "null" ] }, "integration": { "type": [ "string", "null" ], "enum": [ "zapier", "n8n", "make", "other", null ] }, "status": { "type": "string", "enum": [ "active", "failing", "disabled" ] }, "is_active": { "type": "boolean" }, "secret": { "type": "string", "description": "The signing secret (whsec_...). Only in the response that created the subscription." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "id", "target_url", "events", "description", "integration", "status", "is_active", "created_at", "updated_at" ] }, "PaginationLinks": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "CursorMeta": { "type": "object", "properties": { "path": { "type": "string" }, "per_page": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } }, "required": [ "path", "per_page", "next_cursor", "prev_cursor" ] }, "Error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "MergedTicketError": { "type": "object", "properties": { "message": { "type": "string" }, "merged_into": { "$ref": "#/components/schemas/TicketRef" } }, "required": [ "message", "merged_into" ] }, "ValidationError": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] }, "WebhookEnvelope": { "type": "object", "description": "Every webhook body has this envelope; data.object has the same shape the API returns for that object.", "properties": { "id": { "type": "string", "description": "evt_...; the same on every retry and resend." }, "type": { "type": "string", "enum": [ "ticket.created", "ticket.updated", "ticket.status_changed", "ticket.closed", "ticket.assigned", "ticket.replied", "ticket.note_added", "ticket.merged", "ticket.split", "ticket.classified", "ticket.sentiment_dropped", "ticket.linked_issue_status_changed", "customer.created", "conversation.promoted", "csat.rated", "sla.warning", "sla.breached", "ping", "automation.webhook_called" ] }, "api_version": { "type": "string", "const": "v1" }, "created_at": { "type": "string", "format": "date-time" }, "team": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "id", "type", "api_version", "created_at", "team", "data" ] }, "Rating": { "type": "object", "properties": { "score": { "type": [ "integer", "null" ] }, "previous_score": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] }, "has_comment": { "type": "boolean" } }, "required": [ "score", "previous_score", "source", "has_comment" ] }, "Change": { "type": "object", "description": "A field's old and new value.", "properties": { "old": {}, "new": {} }, "required": [ "old", "new" ] } }, "responses": { "Unauthorized": { "description": "Missing, invalid or expired token, an OAuth app the user disconnected, or a browser session instead of a token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Token not scoped to a team you belong to, team not on Premium, IP not allowed, the token lacks the scope the endpoint needs (the message names it), or no permission for that ticket or resource (e.g. customers need an admin or owner token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found, or not visible to the token (other teams' records always answer 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MergedTicket": { "description": "The ticket was merged into another one; merged_into names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergedTicketError" } } } }, "ValidationFailed": { "description": "Validation failed; errors lists the problems per field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "TooManyRequests": { "description": "Rate limit (or the team's monthly ticket limit) reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "headers": { "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "RateLimitLimit": { "description": "Requests allowed per minute for this token.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current minute for this token.", "schema": { "type": "integer" } } } } }