Partner API

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:

  1. Open the assistant that will be used by the integration.
  2. Go to Settings → API Keys.
  3. Select Generate new API key.
  4. Enter a description that identifies the integration.
  5. Select only the required scopes. The * scope grants full access.
  6. 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_KEY

The production base URL is:

https://partners-api.taubot.ai

3. 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:

FieldHow to use it
external_user_idA stable customer identifier from your system. For WhatsApp, use the phone number in international format when instructed for that integration.
input_textThe 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

CodeMeaningWhat to check
401Missing or invalid credentialThe Authorization header and API key validity
403The key cannot perform the operationGranted permissions and requested company
404Assistant or conversation not foundCompany identifier, chat_id, or conversation key
422Invalid request dataRequired fields, data types, and JSON format
5xxTemporary service failureRetry 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.

On this page