Skip to content

Changelog

Dated entries, newest first. Anything that would break an existing integration is called out explicitly.

Additions are not breaking: a new field on a response, a new optional parameter, a new enum member, or a new endpoint. Build clients that ignore fields they do not recognise and tolerate unknown enum values, and these land without your involvement.

Added

  • interactive on POST /messages: up to three reply buttons, or a list of up to ten rows, inside the customer’s 24-hour service window. See sending buttons or a list.
  • buttonReply on every message: the id and title of the button or row a customer tapped, and null on every other message.

Added

  • media on POST /messages: a photo, document, video or voice note by public HTTPS link, inside the customer’s 24-hour service window. See sending a file.

Fixed

  • GET /messages/{id} now gives failureReason for a failed free-text reply or file. It was always null for a message sent straight into a conversation.

Added

  • media on every message: each file’s index, type, mimeType, fileName, sizeBytes, caption, status, url and downloadPath. Webhooks for message.received and message.sent carry it too.
  • GET /conversations/{id}/messages/{messageId}/media/{index} downloads a file the customer sent. Needs read:conversations.
  • The media_not_ready problem code, answered with 409 while a file is still being saved.

Changed

  • richContent.media no longer includes storageKey. It was a path inside tkana’s private storage and could not be used to fetch anything. Read files from media. See files in conversations.

Added

  • POST /tickets/{id}/files uploads a file of up to 10 MB to a ticket as multipart/form-data. Needs write:tickets.
  • GET /tickets/{id}/files/{fileId} downloads it. Needs read:tickets.
  • files on every ticket response: each file’s id, name, type and size. It also lists the files staff uploaded in the portal and the files a customer sent over WhatsApp with the request the ticket was filed from.
  • The payload_too_large problem code, answered with 413.

Notes

  • A file has no URL, in any response. It is read only through the download endpoint, with a key that may read tickets. See files on tickets.
  • attachments is unchanged and still holds links only.

2026-10-01: Pipelines and stages on customers

Section titled “2026-10-01: Pipelines and stages on customers”

Added

  • GET /customer-pipelines lists the organization’s customer pipelines, the entry pipeline first, each with its stages in board order. A stage has an id, a name and the lifecycle it counts as. Needs read:customers.
  • lifecycle on every customer response: lead, qualified, customer, lost, churned, or null when no stage has set it yet.
  • pipelines on every customer response: one entry per pipeline the contact is in, with pipelineId, pipeline, stageId, stage, stageLifecycle and enteredAt. It is a list, so an organization adding a second pipeline does not change its shape.
  • GET /customers?lifecycle=lead lists only contacts with that lifecycle.
  • stage on POST /customers and PATCH /customers/{id}: a stage id from GET /customer-pipelines. The contact’s card in that pipeline moves there. A contact who is not in that pipeline enters it at that stage.
  • The customer.stage_changed webhook, sent once per move of a contact to another stage, whoever made it: staff, the AI agent, a workflow or an API write. data holds the customer, the pipeline, fromStage, toStage and movedAt.

Notes

  • A stage the organization does not have is refused with 422, with one entry in errors naming stage, and nothing in the request is written. A refused POST creates no customer.
  • A contact created without a stage enters the first stage of the entry pipeline.
  • Pipelines and stages are edited in the portal, by the organization’s owners. The API reads them and never changes them.

Added

  • GET /customer-fields lists the fields the organization’s owners defined for its customers: each field’s key, labels, type, required flag and, for a select, its options. Needs read:customers.
  • customFields on every customer response, keyed by field key. A field with no value is absent. A date is YYYY-MM-DD and a select holds the option’s key, not its label.
  • customFields on POST /customers and PATCH /customers/{id}. It is a merge: a key sets that field, null or "" clears it, and fields you leave out keep their values.

Notes

  • A key the organization has not defined, or a value of the wrong type, is refused with 422. Each entry in errors names the field as customFields.<key>, and nothing in the request is written. A refused POST creates no customer.
  • A required field that holds a value cannot be cleared.
  • Fields are created and changed in the portal, by the organization’s owners. The API reads them and never changes them.

2026-09-22 — Reads for tickets, bookings and services

Section titled “2026-09-22 — Reads for tickets, bookings and services”

Added

  • GET /tickets, /tickets/{id} and /tickets/{id}/history. Filter by status, priority, category and customerId; search matches the subject and description by substring and a reference (T-… or the pipeline card’s TK-…) exactly.
  • GET /bookings and /bookings/{id}, with inclusive from/to day bounds.
  • GET /services, /services/{id}/resources, and /services/{id}/resources/{resourceId}/availability. Availability accepts at most 31 days per request.
  • cursor on the customers, conversations, tickets and bookings lists, so a sync can page without risking skipped rows.
  • This documentation site. The reference is generated from the running API, so it cannot describe an endpoint that does not exist or miss one that does.

Notes

  • A booking’s date, startTime and endTime are the organization’s local wall clock, not instants. Availability slots are instants.
  • A sync reports creations and changes, not removals. See syncing.

2026-09-19 — Reads for customers and conversations

Section titled “2026-09-19 — Reads for customers and conversations”

Added

  • GET /customers and /customers/{id}.
  • GET /conversations, /conversations/{id} and /conversations/{id}/messages, with the AI summary on a resolved conversation once it has been written.
  • Organization API keys with scopes, created by owners and admins in the portal.
  • application/problem+json errors carrying a stable code, and X-Request-Id on every response.