# Talqui Developer Hub

- [Welcome to the Talqui Developer Hub](https://docs.talqui.chat/index.md): Simple Customer Service, at scale.
- [Platform changes](https://docs.talqui.chat/changelog.md): A ledger of notable changes to the Talqui Platform that may impact your integrations.
- [Introduction](https://docs.talqui.chat/guides/introduction.md)
- [Quickstart](https://docs.talqui.chat/guides/introduction/quick-start.md)
- [Authentication](https://docs.talqui.chat/guides/introduction/authentication.md)
- [Embedded Authentication (id-token)](https://docs.talqui.chat/guides/introduction/authentication/embedded.md)
- [Guides](https://docs.talqui.chat/guides.md)
- [Platform](https://docs.talqui.chat/guides/platform.md)
- [Campaigns](https://docs.talqui.chat/guides/platform/campaigns.md)
- [Overview](https://docs.talqui.chat/guides/platform/campaigns/overview.md)
- [Entities](https://docs.talqui.chat/guides/platform/campaigns/entities.md)
- [Create Campaign](https://docs.talqui.chat/guides/platform/campaigns/create-campaign.md)
- [Create Campaign Model](https://docs.talqui.chat/guides/platform/campaigns/create-campaign-model.md)
- [Create Campaign Dispatch](https://docs.talqui.chat/guides/platform/campaigns/create-campaign-dispatch.md)
- [Sessions](https://docs.talqui.chat/guides/platform/sessions.md)
- [Session Start](https://docs.talqui.chat/guides/platform/sessions/session-start.md)
- [WhatsApp API Official](https://docs.talqui.chat/guides/platform/sessions/session-start/whatsapp-api-official.md)
- [WhatsApp Business](https://docs.talqui.chat/guides/platform/sessions/session-start/whatsapp-business.md)
- [iFood](https://docs.talqui.chat/guides/platform/sessions/session-start/ifood.md)
- [Generic Channels](https://docs.talqui.chat/guides/platform/sessions/session-start/generic-channels.md)
- [Phone Number Format](https://docs.talqui.chat/guides/platform/sessions/phone-number-format.md)
- [Chatbot (Flow Builder)](https://docs.talqui.chat/guides/bot-builder.md)
- [Overview](https://docs.talqui.chat/guides/bot-builder/overview.md)
- [Message Processing](https://docs.talqui.chat/guides/bot-builder/message-processing.md)
- [Neurons](https://docs.talqui.chat/guides/bot-builder/neurons.md)
- [Neuron: HTTP](https://docs.talqui.chat/guides/bot-builder/neuron-http.md)
- [Neuron: Generic](https://docs.talqui.chat/guides/bot-builder/neuron-generic.md)
- [Plugins](https://docs.talqui.chat/guides/plugins.md)
- [Overview](https://docs.talqui.chat/guides/plugins/overview.md)
- [Getting Started](https://docs.talqui.chat/guides/plugins/getting-started.md)
- [Architecture](https://docs.talqui.chat/guides/plugins/architecture.md)
- [Backend](https://docs.talqui.chat/guides/plugins/backend.md)
- [Widget](https://docs.talqui.chat/guides/plugins/widget.md)
- [Settings](https://docs.talqui.chat/guides/plugins/settings.md)
- [Submitting Your Plugin](https://docs.talqui.chat/guides/plugins/submitting.md)
- [Use Cases](https://docs.talqui.chat/guides/plugins/use-cases.md)
- [Ice Cream Shop](https://docs.talqui.chat/guides/plugins/use-cases/ice-cream-shop.md)
- [AI Capabilities](https://docs.talqui.chat/guides/plugins/use-cases/ai-capabilities.md)
- [Conversation Observer](https://docs.talqui.chat/guides/plugins/use-cases/conversation-observer.md)
- [RTM API Reference (V1)](https://docs.talqui.chat/references/rtm-api/v1.md)
- [Read operator profile](https://docs.talqui.chat/api-reference/services-api/operators/read-operator-profile.md): Returns the authenticated operator's own document — name, photo, phone, roles and notification settings.
- [List operators](https://docs.talqui.chat/api-reference/services-api/operators/list-operators.md): Lists the tenant's operators — the team list — each with the role they hold inside this tenant (`operator`/`manager`/`owner`/`superuser`) and their live presence, or `null` when they are offline.
- [List operator shortcuts](https://docs.talqui.chat/api-reference/services-api/operators/list-operator-shortcuts.md): Lists the shortcuts the requesting operator can see: their own personal shortcuts plus every company-wide one. Ordering is fixed — personal before company-wide, then alphabetical — so pagination stays stable across pages. Returns HTTP 206 instead of 200 when more pages are available.
- [Create operator shortcut](https://docs.talqui.chat/api-reference/services-api/operators/create-operator-shortcut.md): Creates a shortcut for the requesting operator. Unlike the endpoint this replaces, it is a plain create rather than an upsert keyed on the shortcut name — a name already in use is reported as a conflict instead of silently overwriting the existing shortcut.
- [Delete operator shortcut](https://docs.talqui.chat/api-reference/services-api/operators/delete-operator-shortcut.md): Soft-deletes a shortcut. Any files attached to it are deliberately left in storage: messages already dispatched from this shortcut reference the very same objects, so removing them would break chat history.
- [Update operator shortcut](https://docs.talqui.chat/api-reference/services-api/operators/update-operator-shortcut.md): Updates a shortcut in place, identified by its shortcutID. Renaming a shortcut therefore edits the existing record rather than creating a second one, and changing scope is allowed — both were impossible on the endpoint this replaces.
- [Update operator availability](https://docs.talqui.chat/api-reference/services-api/operators/update-operator-availability.md): Updates an operator's presence status (online/away/offline) and, optionally, their push notification token/platform for the current device. Processing happens asynchronously — the response reflects the accepted request, not necessarily the fully-propagated state.
- [List plugin connections by plugin](https://docs.talqui.chat/api-reference/services-api/plugins/list-plugin-connections-by-plugin.md): Lists every tenant that installed the **calling** plugin, with the connection each one configured — what a plugin polls to discover its own install base. Each row carries the connection's `token` and the tenant's provider credentials in `settings`, which is the point: the plugin needs them to act fo…
- [List public plugins](https://docs.talqui.chat/api-reference/services-api/plugins/list-public-plugins.md): Public, unauthenticated listing of the visible plugin catalog. Only non-sensitive fields are returned — credentials, tokens, and other internal configuration are never included.
- [List plugin connections](https://docs.talqui.chat/api-reference/services-api/plugins/list-plugin-connections.md): Lists every plugin the tenant has connected, each with the catalog entry it installs joined in — the data behind the installed-plugins screen. Disabled connections are included (so the screen can offer to switch them back on); deleted ones are not.
- [List operator tenants](https://docs.talqui.chat/api-reference/services-api/tenants/list-operator-tenants.md): Lists every tenant the authenticated operator is a member of, with each tenant's full settings — what backs the tenant switcher after login.
- [List reports](https://docs.talqui.chat/api-reference/services-api/analytics/list-reports.md): Lists the tenant's analytics reports, newest first, with pagination and an optional status filter. Returns HTTP 206 instead of 200 when more pages are available.
- [Emit report](https://docs.talqui.chat/api-reference/services-api/analytics/emit-report.md): Requests generation of an analytics report (PDF) covering one or more pre-arranged groups over a date range. Generation happens asynchronously in the background — this endpoint only creates the pending report record.
- [Read report](https://docs.talqui.chat/api-reference/services-api/analytics/read-report.md): Reads one analytics report. The cheap way to poll a single pending report: it returns `reportStatus` and, once generation lands, the `resultURL` of the printed PDF, resolved from talqui-services-storage per request.
- [Get analytics namespace](https://docs.talqui.chat/api-reference/services-api/analytics/get-analytics-namespace.md): Queries a single analytics namespace (e.g. sessions, messages, credits) over a date range and set of filters, returning the response shape specific to that namespace.
- [List campaigns](https://docs.talqui.chat/api-reference/services-api/campaigns/list-campaigns.md): Lists the tenant's campaigns with pagination, search and sorting. Unlike the legacy campaignList.js, `meta.totalCount`/`totalPages` are real aggregate counts — the frontend no longer needs to walk 5 pages of 200 to approximate a total (see acquireCampaignsStats in talqui-app-web). Returns HTTP 206 i…
- [Create campaign](https://docs.talqui.chat/api-reference/services-api/campaigns/create-campaign.md): Creates a new campaign in `draft` status. Migrated from talqui-core-api's campaignCreate.js — `createdBy`/`updatedBy` are the real authenticated operator here, not the legacy's hardcoded 'TBD'.
- [Get campaigns stats](https://docs.talqui.chat/api-reference/services-api/campaigns/get-campaigns-stats.md): Aggregate campaign count by status for the tenant, in one query. Replaces the frontend's acquireCampaignsStats workaround (walking up to 5 pages of 200 campaigns and counting client-side because the legacy core-api list endpoint has no aggregate counts).
- [Read campaign](https://docs.talqui.chat/api-reference/services-api/campaigns/read-campaign.md): Reads a single campaign. Unlike the legacy campaignUpdate.js path (which silently no-ops on a missing campaignID), this always 404s when the campaign doesn't exist for the tenant.
- [Delete campaign](https://docs.talqui.chat/api-reference/services-api/campaigns/delete-campaign.md): Soft-deletes a campaign: it leaves every list and stat for the tenant, while its dispatches and the sessions they created keep referencing it. This does not stop a campaign that is already sending — cancel does.
- [Update campaign](https://docs.talqui.chat/api-reference/services-api/campaigns/update-campaign.md): Updates a campaign's metadata and/or (draft-only) recipients/model/ schedule. Changing campaignContactIDs, campaignContactAttributes, campaignModelID or dispatchAt is rejected once the campaign has left `draft` — the legacy campaignUpdate.js has no such guard.
- [Cancel campaign](https://docs.talqui.chat/api-reference/services-api/campaigns/cancel-campaign.md): Cancels a campaign in `scheduled` OR `processing` status (extends the legacy core-api endpoint, which only accepted `scheduled`) — a POST action route instead of the legacy's DELETE, since this is a state transition, not a resource deletion. Only dispatches still `pending`/ `processing` are canceled…
- [Get campaign progress](https://docs.talqui.chat/api-reference/services-api/campaigns/get-campaign-progress.md): Read-only aggregate progress for a single campaign — same shape as the `campaign:dispatch:progress` socket event talqui-core-api's dispatch engine emits (campaigns backend epic, task 15), so a client can poll this as a drift-correction fallback whenever it may have missed a socket event (reconnect,…
- [Schedule campaign](https://docs.talqui.chat/api-reference/services-api/campaigns/schedule-campaign.md): Resolves the final recipient audience (filters + manual + imported − excluded), pre-computes and validates every contact's template variables, persists one CampaignDispatches document per contact with campaignDispatchVariables already filled, and enqueues them to SQS in batch — replacing talqui-core…
- [List campaign models](https://docs.talqui.chat/api-reference/services-api/campaigns-models/list-campaign-models.md): Lists the tenant's campaign templates with pagination, search and sorting. Returns HTTP 206 instead of 200 when more pages are available.
- [Create campaign model](https://docs.talqui.chat/api-reference/services-api/campaigns-models/create-campaign-model.md): Registers a new WhatsApp campaign message template for the tenant on the given channel/provider, then submits it for provider approval. The template name is validated against provider-specific rules before being reserved.
- [Read campaign model](https://docs.talqui.chat/api-reference/services-api/campaigns-models/read-campaign-model.md): Fetches a single campaign template by ID, including the JSON snippet needed to request that template through the provider's API.
- [Update campaign model](https://docs.talqui.chat/api-reference/services-api/campaigns-models/update-campaign-model.md): Updates the tags and/or metadata of an existing campaign template. This does not resubmit the template to the provider — it only patches the record's own fields.
- [Delete campaign model](https://docs.talqui.chat/api-reference/services-api/campaigns-models/delete-campaign-model.md): Deletes a campaign template. This does not revoke the template with the provider — it only removes Talqui's own record.
- [List contact imports](https://docs.talqui.chat/api-reference/services-api/contacts/list-contact-imports.md): Recent imports for the tenant, newest first, each carrying the same progress shape as the single-import endpoint so a list row and a detail view render from one component.
- [Create contact import](https://docs.talqui.chat/api-reference/services-api/contacts/create-contact-import.md): Registers an already-uploaded CSV as a pending import and returns at once. Only the first bytes are read in the request, to settle the file's encoding and check the mapped columns against its header row: a 200.000-row file cannot be walked inside an HTTP round-trip, so the response is an acknowledge…
- [Get contact import](https://docs.talqui.chat/api-reference/services-api/contacts/get-contact-import.md): Current progress of one import. The percentage is computed here rather than by the client — the legacy screen derived it from per-contact socket events with no denominator, which is why its bar never reached the end.
- [Read contact](https://docs.talqui.chat/api-reference/services-api/contacts/read-contact.md): Looks up a single contact, either by contactID or by a channel + external identifier pair (e.g. a WhatsApp phone number).
- [Resolve contacts segment](https://docs.talqui.chat/api-reference/services-api/contacts/resolve-contacts-segment.md): Resolves the paginated contact audience matching the given filter rules and channel — the real backend for the segment builder in the campaign wizard's recipients step (replaces the client-side-only resolution the frontend uses as a documented stopgap today). Returns HTTP 206 instead of 200 when mor…
- [Count contacts segment](https://docs.talqui.chat/api-reference/services-api/contacts/count-contacts-segment.md): Counts contacts matching the given filter rules and channel, applying the mandatory contactBlock/contactExternal[channel] reachability gates regardless of what the client's filters request. Used by the campaign wizard's recipients step to show a live audience count as the operator builds a segment.
- [List contacts tags](https://docs.talqui.chat/api-reference/services-api/contacts/list-contacts-tags.md): Lists the distinct contact tags in use across the tenant, for the campaign segment builder's tag picker. Uses the {tenantID,contactTags} compound index (campaigns backend epic, task 08) — the equivalent endpoint in core-api (contactTags.js) has no such index and runs an unindexed distinct() over the…
- [Read contact](https://docs.talqui.chat/api-reference/services-api/contacts/read-contact-1.md): Looks up a single contact, either by contactID or by a channel + external identifier pair (e.g. a WhatsApp phone number).
- [Create handoff link](https://docs.talqui.chat/api-reference/services-api/handoff-links/create-handoff-link.md): Issues a single-use link that lets the contact continue the conversation on a different channel while staying the same contact.
- [List handoff destinations](https://docs.talqui.chat/api-reference/services-api/handoff-links/list-handoff-destinations.md): Lists the channels this contact can actually be invited to from the given session — the picker that feeds `POST /handoff-links`.
- [Read handoff link](https://docs.talqui.chat/api-reference/services-api/handoff-links/read-handoff-link.md): Reads a handoff link without consuming it, so an operator can re-open the link they generated or a caller can check whether a token was already used.
- [Redeem handoff link](https://docs.talqui.chat/api-reference/services-api/handoff-links/redeem-handoff-link.md): Consumes a handoff link and returns the contact it was issued for, so the caller can attach the new conversation to that existing contact instead of creating a duplicate.
- [List inboxes](https://docs.talqui.chat/api-reference/services-api/inboxes/list-inboxes.md): Lists the inboxes the calling operator may see — the conversation sidebar.
- [Read message by external ID](https://docs.talqui.chat/api-reference/services-api/messages/read-message-by-external-id.md): Resolves a single message by its provider-side id, for rendering the target of a reply quote or a reaction.
- [Look message](https://docs.talqui.chat/api-reference/services-api/messages/look-message.md): Roda um modelo de visão sobre o anexo (`messageKey: 'file'` ou `'image'`) de uma mensagem e grava a descrição em `messageValue.looker`.
- [Transcribe message](https://docs.talqui.chat/api-reference/services-api/messages/transcribe-message.md): Transcreve o áudio de uma mensagem (`messageKey: 'audio'` ou `'voice'`) e grava o resultado em `messageValue.transcription`.
- [Enqueue message transcription](https://docs.talqui.chat/api-reference/services-api/messages/enqueue-message-transcription.md): Enfileira a transcrição do áudio de uma mensagem (`messageKey: 'audio'` ou `'voice'`) e responde **202 Accepted** imediatamente.
- [List notifications](https://docs.talqui.chat/api-reference/services-api/notifications/list-notifications.md): Returns the operator's unread notification counts, grouped by category (e.g. per inbox), for the requesting operator's own session.
- [Open session](https://docs.talqui.chat/api-reference/services-api/sessions/open-session.md): Reopens a closed session, assigning it to the requesting operator and notifying connected clients over the realtime socket.
- [Generate session transcription](https://docs.talqui.chat/api-reference/services-api/sessions/generate-session-transcription.md): Gera a transcrição textual completa da conversa, publica o arquivo `.txt` no storage e devolve uma URL privada e assinada, válida por 30 dias. O arquivo é privado e permanece; só o link expira. Depois de 30 dias, chame este endpoint de novo para obter um link novo.
- [Send session transcription](https://docs.talqui.chat/api-reference/services-api/sessions/send-session-transcription.md): Envia a conversa por e-mail para o endereço informado. O corpo do e-mail traz a conversa renderizada; o arquivo `.txt` só é gerado e anexado quando `attachTranscription` é `true` (padrão) — com `false`, nada é gravado no storage.
- [List session motives](https://docs.talqui.chat/api-reference/services-api/settings/list-session-motives.md): Lists the tenant's close-session reasons — the options an operator picks from when ending a conversation, and the source of the readable labels the analytics `closeMotive` dimension reports against.
- [List variables](https://docs.talqui.chat/api-reference/services-api/settings/list-variables.md): Lists the tenant's custom variables, optionally filtered by scope, plugin connection or key.
- [Upsert variables](https://docs.talqui.chat/api-reference/services-api/settings/upsert-variables.md): Creates or updates one or more custom variables in a single batch. Variables scoped to a plugin connection require both a pluginConnectionID and a pluginURN.
- [Delete variables](https://docs.talqui.chat/api-reference/services-api/settings/delete-variables.md): Deletes one or more custom variables (tenant-wide or scoped to a specific plugin connection) by key.
- [Get tenant setup](https://docs.talqui.chat/api-reference/services-api/setup/get-tenant-setup.md): Returns the tenant's onboarding checklist state (WhatsApp, Telegram, teammates, chatbox, shortcuts) used to drive the setup/getting-started screen.
- [Create signed upload URL](https://docs.talqui.chat/api-reference/services-api/uploads/create-signed-upload-url.md): Issues a short-lived pre-signed PUT so the browser uploads straight to storage, plus the public URL the object will be served from. The client must send the same `Content-Type` on the PUT, since it is part of the signature.
- [Install pre](https://docs.talqui.chat/api-reference/helpdesk-api/install/install-pre.md): Creates (or resolves, on a retry) the tenant's help center and answers with the `helpdeskID` the core API persists as `pluginConnection.settings.helpdeskID`.
- [Check helpdesk slug](https://docs.talqui.chat/api-reference/helpdesk-api/helpdesk/check-helpdesk-slug.md): Previews whether a public address (`helpdeskSlug`) is available, applying the exact rules the save enforces: `slugify()` normalization, the reserved list, and the global uniqueness index. Answers per keystroke for the onboarding's address field, so the operator never discovers a conflict only after…
- [Read helpdesk](https://docs.talqui.chat/api-reference/helpdesk-api/helpdesk/read-helpdesk.md): Returns the tenant's help center in full, audit fields and all — this is the authoring view, behind `useDualAuth`, not the public projection.
- [Update helpdesk](https://docs.talqui.chat/api-reference/helpdesk-api/helpdesk/update-helpdesk.md): Saves the help center's identity, theme, support channels and custom domains, then drops the hostname resolution cache — the cached `resolve` payload carries both the theme and the domain list, so without the invalidation a theme change would take up to the full TTL to show up and a removed hostname…
- [Get helpdesk catalog](https://docs.talqui.chat/api-reference/helpdesk-api/helpdesk/get-helpdesk-catalog.md): The published catalog of the tenant's help center — categories, articles and each article's absolute public URL — in one call, for a caller that needs to pick an article and paste its link.
- [Add helpdesk domain](https://docs.talqui.chat/api-reference/helpdesk-api/helpdesk/add-helpdesk-domain.md): Registers a branded custom domain for the help center: pre-registers the hostname as a Cloudflare custom hostname and stores it as `pending`. The response carries the fixed CNAME target the customer must point the domain's DNS at — the target is a constant of this API, identical for every domain — p…
- [Remove helpdesk domain](https://docs.talqui.chat/api-reference/helpdesk-api/helpdesk/remove-helpdesk-domain.md): Removes a custom domain: deletes the custom hostname on Cloudflare first, then drops the entry from the help center — in that order, so a failure never leaves an invisible hostname consuming the Cloudflare quota. The hostname stops resolving to this help center immediately.
- [Refresh helpdesk domain](https://docs.talqui.chat/api-reference/helpdesk-api/helpdesk/refresh-helpdesk-domain.md): Re-checks the domain's provisioning state against Cloudflare on demand — the "Verify again" button. Idempotent: while the CNAME is not in place the domain stays `pending` with a pt-BR `statusReason` explaining what is missing; once Cloudflare reports the hostname and its certificate active, the doma…
- [Get public article](https://docs.talqui.chat/api-reference/helpdesk-api/public/get-public-article.md): Article page: the published body, its category and the other articles of that category.
- [Rate article](https://docs.talqui.chat/api-reference/helpdesk-api/public/rate-article.md): Records one vote on a published article, plus the optional free-text feedback that is the most valuable part of the block — it is where a customer tells the operator the article is wrong.
- [Register article view](https://docs.talqui.chat/api-reference/helpdesk-api/public/register-article-view.md): Increments the daily hit bucket of an article.
- [Get public category](https://docs.talqui.chat/api-reference/helpdesk-api/public/get-public-category.md): Category page: the category, its published articles and its siblings.
- [Get public home](https://docs.talqui.chat/api-reference/helpdesk-api/public/get-public-home.md): Home page payload: the help center, its featured articles and its published categories.
- [Resolve helpdesk](https://docs.talqui.chat/api-reference/helpdesk-api/public/resolve-helpdesk.md): Turns the hostname the visitor arrived on into the help center that answers for it, with its theme and support channels — the payload every SSR render starts from.
- [Search articles](https://docs.talqui.chat/api-reference/helpdesk-api/public/search-articles.md): Ranked search over the published articles of the help center this hostname resolves to.
- [List articles](https://docs.talqui.chat/api-reference/helpdesk-api/articles/list-articles.md): Every article of the tenant's help center, drafts included, optionally narrowed by category or status. Authoring listing — the public surface never returns anything but published articles.
- [Create article](https://docs.talqui.chat/api-reference/helpdesk-api/articles/create-article.md): Creates an article. It is always born in `draft` with an empty published body: the only way content reaches a public page is an explicit publish.
- [Delete article](https://docs.talqui.chat/api-reference/helpdesk-api/articles/delete-article.md): Soft-deletes an article. It leaves every public surface immediately and releases its slug, so the same URL can be recreated later.
- [Update article](https://docs.talqui.chat/api-reference/helpdesk-api/articles/update-article.md): Patches an article's metadata and its draft. It never writes the live `articleContent*` fields — that only happens on publish, which is what lets an operator edit for an hour without the page going blank in the meantime.
- [Publish article](https://docs.talqui.chat/api-reference/helpdesk-api/articles/publish-article.md): Puts the draft on the air: copies `articleDraft` over the live `articleContent*` fields, bumps `articleVersion`, stamps `publishedAt` and `publishedBy`, clears the draft, and invalidates every cached public payload of the help center.
- [List categories](https://docs.talqui.chat/api-reference/helpdesk-api/categories/list-categories.md): Every category of the tenant's help center, drafts included — this is the authoring listing. The public one lives at `/v1/public/*` and only ever returns published documents.
- [Create category](https://docs.talqui.chat/api-reference/helpdesk-api/categories/create-category.md): Creates a category in the tenant's help center. The slug is normalized server-side and checked for collisions inside this help center only — two tenants may both own `getting-started`.
- [Delete category](https://docs.talqui.chat/api-reference/helpdesk-api/categories/delete-category.md): Soft-deletes a category: it disappears from every surface and releases its slug, so the same URL can be recreated later. Articles pointing at it are left alone — they stop showing a breadcrumb, they do not vanish.
- [Update category](https://docs.talqui.chat/api-reference/helpdesk-api/categories/update-category.md): Patches a category. Only the fields present in the body change — a caller sending just `categoryOrder` does not blank the description it never mentioned.

## OpenAPI Specs

- [helpdesk](/api/helpdesk.yaml)
- [services-api](/api/services-api.yaml)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.