API de Parceiros

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 rotaUso principal
POST /agent/{company_domain}Enviar uma mensagem ao assistente e receber a resposta
POST /agent/{company_domain}/batchProcessar 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}/chatsListar conversas com filtros e paginação
GET /agent/{company_domain}/chat_history/{conversation_key}Consultar as mensagens de uma conversa
GET /whatsapp/{company_domain}/statusVerificar o estado da conexão do WhatsApp

Identificadores usados nas rotas

IdentificadorOrigem
company_domainIdentificador do assistente exibido na URL do painel
external_user_idIdentificador estável do cliente no sistema do parceiro
chat_idIdentificador devolvido ao iniciar ou continuar uma conversa
conversation_keyChave 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.

  • 401 indica que a credencial não foi aceita.
  • 403 indica 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 1
  • per_page: quantidade de itens por resposta
  • sort: asc para mais antigos primeiro ou desc para mais recentes primeiro
  • cursor: 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_id quando 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.

On this page