Getting started
Authenticate your integration and send the first message to the TAU assistant.
Getting started
This guide covers the minimum flow required to authenticate your integration, send a message, and continue the same conversation.
1. Generate an API key
In the TAU dashboard:
- Open the assistant that will be used by the integration.
- Go to Settings → API Keys.
- Select Generate new API key.
- Enter a description that identifies the integration.
- Select only the required scopes. The
*scope grants full access. - Select Add and store the generated key in a secrets manager or server-side environment variable.
You will also need the assistant identifier used in the integration URL.
export TAU_API_KEY="YOUR_API_KEY"Do not use the key in browser code or send it to mobile applications. Call the API through your backend.
2. Configure authentication
The API uses Bearer authentication. Send the key with every protected request:
Authorization: Bearer YOUR_API_KEYThe production base URL is:
https://partners-api.taubot.ai3. Send the first message
Replace ASSISTANT_IDENTIFIER with the assistant identifier:
curl --request POST \
"https://partners-api.taubot.ai/agent/ASSISTANT_IDENTIFIER" \
--header "Authorization: Bearer $TAU_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"external_user_id": "customer-123",
"input_text": "Hi! I would like to learn more about your services.",
"channel": "web"
}'The two required fields are:
| Field | How to use it |
|---|---|
external_user_id | A stable customer identifier from your system. For WhatsApp, use the phone number in international format when instructed for that integration. |
input_text | The message to be processed by the assistant. |
Use only the personal data required for the customer interaction and connected channel.
4. Store the conversation identifier
A successful response follows this basic format:
{
"message": "Hi! How can I help?",
"chat_id": "conversation-identifier",
"summary": "",
"status": "in_progress",
"assistant_enabled": true
}Store the chat_id with the customer record. It preserves context in subsequent messages.
5. Continue the conversation
Send the same external_user_id again and include the returned chat_id:
curl --request POST \
"https://partners-api.taubot.ai/agent/ASSISTANT_IDENTIFIER" \
--header "Authorization: Bearer $TAU_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"external_user_id": "customer-123",
"chat_id": "conversation-identifier",
"input_text": "What times are available?",
"channel": "web"
}'If chat_id is omitted, the API may start a new conversation.
Safe retries
When the source system already provides a unique message identifier, also send external_message_id. This helps your integration identify the same message during a retry.
For temporary errors, retry with progressive delays. Do not repeat a request indefinitely without checking whether it has already been processed.
Common errors
| Code | Meaning | What to check |
|---|---|---|
401 | Missing or invalid credential | The Authorization header and API key validity |
403 | The key cannot perform the operation | Granted permissions and requested company |
404 | Assistant or conversation not found | Company identifier, chat_id, or conversation key |
422 | Invalid request data | Required fields, data types, and JSON format |
5xx | Temporary service failure | Retry with progressive delays and preserve the message identifier |
Next step
See the API reference for available operations, pagination options, and access rules for conversation history and media.