API de Parceiros

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:

  1. Abra o assistente que será usado pela integração.
  2. Acesse Configurações → Chaves de API.
  3. Clique em Gerar nova chave de API.
  4. Preencha uma descrição que identifique a integração.
  5. Selecione somente os escopos necessários. O escopo * concede acesso total.
  6. 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_API

A URL base de produção é:

https://partners-api.taubot.ai

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

CampoComo usar
external_user_idIdentificador 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_textMensagem 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ódigoSignificadoO que verificar
401Credencial ausente ou inválidaCabeçalho Authorization e validade da chave
403A chave não tem permissão para a operaçãoPermissões concedidas e empresa solicitada
404Assistente ou conversa não encontradoIdentificador da empresa, chat_id ou chave da conversa
422Dados da requisição inválidosCampos obrigatórios, tipos e formato do JSON
5xxFalha temporária no serviçoTente 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.

On this page