Referência da API
Consulte as principais operações, convenções e regras da API de Parceiros da TAU.
Referência da API
A referência interativa é a fonte atualizada para formatos de requisição, campos opcionais, exemplos de resposta e testes controlados.
Abrir a referência interativa da API de Parceiros
Use apenas as operações liberadas para sua integração. Rotas identificadas como internas não fazem parte do contrato público para parceiros.
Principais operações
A tabela abaixo resume as operações mais comuns. O contrato completo permanece na referência interativa.
| Método e rota | Uso principal |
|---|---|
POST /agent/{company_domain} | Enviar uma mensagem ao assistente e receber a resposta |
POST /agent/{company_domain}/batch | Processar um conjunto de mensagens em sequência |
PATCH /agent/{company_domain}/assistant_status/{external_user_id}/{chat_id} | Ativar ou pausar o assistente em uma conversa |
GET /bot/{company_domain}/chat_status/{conversation_key} | Consultar o estado atual de uma conversa |
POST /agent/{company_domain}/last_chat_id/{external_user_id} | Recuperar a conversa ativa de um cliente e, conforme o parâmetro usado, criar uma quando não houver |
POST /user/{company_domain}/{external_user_id} | Criar ou recuperar a identidade do cliente na integração |
GET /agent/{company_domain}/chats | Listar conversas com filtros e paginação |
GET /agent/{company_domain}/chat_history/{conversation_key} | Consultar as mensagens de uma conversa |
GET /whatsapp/{company_domain}/status | Verificar o estado da conexão do WhatsApp |
Identificadores usados nas rotas
| Identificador | Origem |
|---|---|
company_domain | Identificador do assistente exibido na URL do painel |
external_user_id | Identificador estável do cliente no sistema do parceiro |
chat_id | Identificador devolvido ao iniciar ou continuar uma conversa |
conversation_key | Chave devolvida na listagem de conversas e usada nas consultas de status e histórico |
Não tente criar ou deduzir identificadores que devem ser devolvidos pela API.
Permissões
Cada chave de API é vinculada à empresa e às operações autorizadas. A mesma chave não deve ser reutilizada entre empresas ou ambientes.
401indica que a credencial não foi aceita.403indica que a credencial foi aceita, mas não tem a permissão necessária.
Solicite somente as permissões necessárias para a integração.
Paginação de conversas e mensagens
A listagem de conversas e o histórico aceitam paginação por página ou por cursor:
page: número da página, começando em 1per_page: quantidade de itens por respostasort:ascpara mais antigos primeiro oudescpara mais recentes primeirocursor: ponto de continuação devolvido pela resposta anterior
Para volumes maiores ou dados atualizados enquanto a consulta acontece, prefira o cursor. Ao usar cursor, não dependa do valor de page.
A listagem de conversas aceita até 100 itens por resposta. O histórico aceita até 200 mensagens por resposta.
Histórico e mídias
O histórico pode incluir mensagens de clientes, do assistente e da equipe, além de imagens, áudios, vídeos e documentos quando disponíveis.
- Datas e horários são retornados em UTC no formato ISO 8601.
- Links temporários de mídia expiram por segurança. Baixe ou processe o arquivo enquanto o link estiver válido.
- Não registre o corpo completo das conversas ou links de mídia em logs sem necessidade e proteção adequadas.
Versionamento
Algumas respostas incluem a versão no corpo e no cabeçalho X-API-Version. Preserve esses valores na integração e revise a referência interativa antes de adotar uma nova versão.
Boas práticas de produção
- Mantenha chaves em um gerenciador de segredos.
- Defina timeout para todas as chamadas.
- Faça novas tentativas apenas em falhas temporárias e com espera progressiva.
- Use
external_message_idquando houver um identificador estável da mensagem de origem. - Valide os dados recebidos antes de exibi-los ou salvá-los.
- Restrinja o acesso ao histórico de conversas de acordo com a LGPD e as políticas da sua empresa.
Para dúvidas sobre o contrato ou o comportamento da integração, entre em contato com meajuda@taubot.ai.