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 route | Primary use |
|---|---|
POST /agent/{company_domain} | Send a message to the assistant and receive its response |
POST /agent/{company_domain}/batch | Process 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}/chats | List conversations with filters and pagination |
GET /agent/{company_domain}/chat_history/{conversation_key} | Retrieve the messages in a conversation |
GET /whatsapp/{company_domain}/status | Check the WhatsApp connection state |
Route identifiers
| Identifier | Source |
|---|---|
company_domain | Assistant identifier shown in the dashboard URL |
external_user_id | Stable customer identifier in the partner system |
chat_id | Identifier returned when starting or continuing a conversation |
conversation_key | Key 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.
401means the credential was not accepted.403means 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 1per_page: number of items in each responsesort:ascfor oldest first ordescfor newest firstcursor: 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_idwhen 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.