Partner API

API reference

Review the main operations, conventions, and rules of the TAU Partner API.

API reference

The interactive reference is the current source for request formats, optional fields, response examples, and controlled tests.

Open the interactive Partner API reference

Use only the operations enabled for your integration. Routes identified as internal are not part of the public partner contract.

Main operations

The table below summarizes the most common operations. The complete contract remains available in the interactive reference.

Method and routePrimary use
POST /agent/{company_domain}Send a message to the assistant and receive its response
POST /agent/{company_domain}/batchProcess a set of messages in sequence
PATCH /agent/{company_domain}/assistant_status/{external_user_id}/{chat_id}Enable or pause the assistant in a conversation
GET /bot/{company_domain}/chat_status/{conversation_key}Retrieve the current state of a conversation
POST /agent/{company_domain}/last_chat_id/{external_user_id}Retrieve a customer's active conversation and, depending on the request parameter, create one when none exists
POST /user/{company_domain}/{external_user_id}Create or retrieve the customer identity for the integration
GET /agent/{company_domain}/chatsList conversations with filters and pagination
GET /agent/{company_domain}/chat_history/{conversation_key}Retrieve the messages in a conversation
GET /whatsapp/{company_domain}/statusCheck the WhatsApp connection state

Route identifiers

IdentifierSource
company_domainAssistant identifier shown in the dashboard URL
external_user_idStable customer identifier in the partner system
chat_idIdentifier returned when starting or continuing a conversation
conversation_keyKey returned in the conversation list and used for status and history requests

Do not create or infer identifiers that must be returned by the API.

Permissions

Each API key is bound to a company and its authorized operations. Do not reuse the same key across companies or environments.

  • 401 means the credential was not accepted.
  • 403 means the credential was accepted but lacks the required permission.

Request only the permissions required by the integration.

Conversation and message pagination

Conversation lists and history support page-based and cursor-based pagination:

  • page: page number, starting at 1
  • per_page: number of items in each response
  • sort: asc for oldest first or desc for newest first
  • cursor: continuation point returned by the previous response

For larger volumes or data that may change during retrieval, prefer cursor pagination. When using cursor, do not rely on the page value.

Conversation lists accept up to 100 items per response. Conversation history accepts up to 200 messages per response.

History and media

Conversation history may include messages from customers, the assistant, and team members, as well as images, audio, video, and documents when available.

  • Dates and times are returned in UTC using ISO 8601.
  • Temporary media links expire for security. Download or process the file while the link is valid.
  • Do not log complete conversation bodies or media links without a clear need and appropriate protection.

Versioning

Some responses include the version in the response body and the X-API-Version header. Preserve these values in your integration and review the interactive reference before adopting a new version.

Production best practices

  • Keep keys in a secrets manager.
  • Set a timeout for every request.
  • Retry only temporary failures and use progressive delays.
  • Send external_message_id when the source message has a stable identifier.
  • Validate received data before displaying or storing it.
  • Restrict access to conversation history according to applicable privacy requirements and your company policies.

For questions about the contract or integration behavior, contact meajuda@taubot.ai.

On this page