Primeiros passos
Autentique sua integração e envie a primeira mensagem para o assistente TAU.
Primeiros passos
Este guia mostra o fluxo mínimo para autenticar sua integração, enviar uma mensagem e continuar a mesma conversa.
1. Gere uma chave de API
No painel TAU:
- Abra o assistente que será usado pela integração.
- Acesse Configurações → Chaves de API.
- Clique em Gerar nova chave de API.
- Preencha uma descrição que identifique a integração.
- Selecione somente os escopos necessários. O escopo
*concede acesso total. - Clique em Adicionar e guarde a chave gerada em um gerenciador de segredos ou variável de ambiente no seu servidor.
Você também precisará do identificador do assistente usado na URL da integração.
export TAU_API_KEY="SUA_CHAVE_DE_API"Não use a chave em código executado no navegador nem a envie para aplicativos móveis. Faça as chamadas à API pelo seu backend.
2. Configure a autenticação
A API usa autenticação Bearer. Envie a chave em todas as requisições protegidas:
Authorization: Bearer SUA_CHAVE_DE_APIA URL base de produção é:
https://partners-api.taubot.ai3. Envie a primeira mensagem
Substitua IDENTIFICADOR_DO_ASSISTENTE pelo identificador do assistente:
curl --request POST \
"https://partners-api.taubot.ai/agent/IDENTIFICADOR_DO_ASSISTENTE" \
--header "Authorization: Bearer $TAU_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"external_user_id": "cliente-123",
"input_text": "Olá! Quero saber mais sobre os serviços.",
"channel": "web"
}'Os dois campos obrigatórios são:
| Campo | Como usar |
|---|---|
external_user_id | Identificador estável do cliente no seu sistema. No WhatsApp, use o telefone no formato internacional quando essa for a orientação da integração. |
input_text | Mensagem que será processada pelo assistente. |
Use somente os dados pessoais necessários para o atendimento e para o canal conectado.
4. Guarde o identificador da conversa
Uma resposta bem-sucedida segue este formato básico:
{
"message": "Olá! Como posso ajudar?",
"chat_id": "identificador-da-conversa",
"summary": "",
"status": "in_progress",
"assistant_enabled": true
}Guarde o chat_id junto ao cliente. Ele mantém o contexto nas mensagens seguintes.
5. Continue a conversa
Envie novamente o mesmo external_user_id e inclua o chat_id recebido:
curl --request POST \
"https://partners-api.taubot.ai/agent/IDENTIFICADOR_DO_ASSISTENTE" \
--header "Authorization: Bearer $TAU_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"external_user_id": "cliente-123",
"chat_id": "identificador-da-conversa",
"input_text": "Quais são os horários disponíveis?",
"channel": "web"
}'Se chat_id não for enviado, a API pode iniciar uma nova conversa.
Reenvio seguro
Quando a mensagem vier de um sistema que já fornece um identificador único, envie também external_message_id. Isso ajuda sua integração a identificar a mesma mensagem em uma nova tentativa.
Para erros temporários, use novas tentativas com espera progressiva. Não repita indefinidamente uma requisição sem confirmar se ela já foi processada.
Erros mais comuns
| Código | Significado | O que verificar |
|---|---|---|
401 | Credencial ausente ou inválida | Cabeçalho Authorization e validade da chave |
403 | A chave não tem permissão para a operação | Permissões concedidas e empresa solicitada |
404 | Assistente ou conversa não encontrado | Identificador da empresa, chat_id ou chave da conversa |
422 | Dados da requisição inválidos | Campos obrigatórios, tipos e formato do JSON |
5xx | Falha temporária no serviço | Tente novamente com espera progressiva e preserve o identificador da mensagem |
Próximo passo
Consulte a referência da API para conhecer as operações disponíveis, as opções de paginação e as regras de acesso a histórico e mídias.