Referência da API

URL base e cabeçalhos

https://platform.toptalking.com.br/v1

Cabeçalho	Quando	Valor
Authorization	Sempre	Bearer tt_live_... (ou use X-Api-Key: tt_live_...)
Content-Type	Requisições com corpo (POST, PATCH)	application/json
Idempotency-Key	Opcional, em POST que cria algo	Um valor único por operação. Veja Idempotência.

Toda resposta traz X-Request-Id e os cabeçalhos de limite de uso. Erros seguem o formato padrão e listas usam paginação por cursor.

Erros que qualquer rota pode responder

Cada endpoint lista os seus erros específicos. Além deles, qualquer rota pode responder:

HTTP	code	Quando acontece
401	missing_api_key, invalid_api_key, revoked_api_key, expired_api_key	Problema com a chave.
403	read_only_key	Chave somente leitura em qualquer método que não seja GET.
429	rate_limit_exceeded	Mais de 120 requisições por minuto (respeite Retry-After).
500, 502	internal_error	Falha inesperada ou passageira. Tente de novo.
503	service_unavailable	API temporariamente indisponível. Tente de novo.
504	timeout	A requisição demorou demais. Tente de novo com a mesma Idempotency-Key.

Sobre os exemplos

Cada endpoint tem exemplos em curl, JavaScript (fetch nativo: Node 18+, Deno, Bun, Edge Functions) e Python (biblioteca requests). Todos leem a chave da variável de ambiente TOPTALKING_API_KEY e devem rodar no seu backend — nunca no navegador. Em Supabase Edge Functions, troque process.env.TOPTALKING_API_KEY por Deno.env.get('TOPTALKING_API_KEY').

Os exemplos usam sempre os mesmos dados fictícios: a organização Loja Aurora, o WhatsApp Vendas (d781e759-…), a cliente Maria Souza (3f1c2b9a-…, 5511999998888) e a atendente Carla Mendes (4083deb8-…).

Endpoints

Conta

Método	Caminho	O que faz
GET	/me	Dados da chave e da organização (teste da chave)

Canais e conexões

Método	Caminho	O que faz
GET	/channels	Listar canais (WhatsApp e Chat do site) e o status de cada um
POST	/channels	Criar canal e iniciar a conexão de um WhatsApp (devolve o QR Code)
GET	/channels/{channel_id}	Buscar canal
PATCH	/channels/{channel_id}	Renomear canal
DELETE	/channels/{channel_id}	Remover canal de WhatsApp
POST	/channels/{channel_id}/connect	Gerar novo QR Code ou código de pareamento (reconectar)
GET	/channels/{channel_id}/qr	QR Code atual e status da conexão (consulte a cada 3–5 s)
POST	/channels/{channel_id}/disconnect	Desconectar o WhatsApp

Passo a passo: Conectar um WhatsApp por QR Code.

Contatos

Método	Caminho	O que faz
GET	/contacts	Listar e buscar contatos (filtros por etapa, canal, grupo, responsável…)
POST	/contacts	Criar ou atualizar contato pelo telefone
GET	/contacts/{contact_id}	Buscar contato
PATCH	/contacts/{contact_id}	Atualizar contato, mover no Kanban, atribuir, fixar, escolher agente, ligar/desligar IA, finalizar, arquivar
GET	/contacts/{contact_id}/messages	Histórico da conversa
POST	/contacts/{contact_id}/read	Marcar conversa como lida

Mensagens

Método	Caminho	O que faz
POST	/messages	Enviar mensagem (texto e/ou mídia), também para grupos
GET	/messages/{message_id}	Buscar mensagem e status de entrega
PATCH	/messages/{message_id}	Editar mensagem enviada (até 15 min)
DELETE	/messages/{message_id}	Apagar para todos (até 48 h) ou só no painel
POST	/messages/{message_id}/reaction	Reagir (ou remover a reação) com emoji

Grupos

Método	Caminho	O que faz
GET	/groups	Listar grupos do WhatsApp (o id é um contact_id)
GET	/groups/{group_id}/participants	Participantes e administradores do grupo

Kanban

Método	Caminho	O que faz
GET	/stages	Listar etapas do Kanban (para mover cards, use PATCH /contacts/{contact_id})

Mensagens agendadas

Método	Caminho	O que faz
GET	/scheduled-messages	Listar mensagens agendadas
POST	/scheduled-messages	Agendar mensagem
GET	/scheduled-messages/{scheduled_message_id}	Buscar mensagem agendada
DELETE	/scheduled-messages/{scheduled_message_id}	Cancelar mensagem agendada

Equipe

Método	Caminho	O que faz
GET	/members	Listar membros da equipe
GET	/members/{member_id}	Buscar membro

Para atribuir uma conversa, veja Atribuir uma conversa.

Agentes de IA

Método	Caminho	O que faz
GET	/ai-agents	Listar agentes de IA
GET	/ai-agents/{agent_id}	Buscar agente de IA
PATCH	/ai-agents/{agent_id}	Ligar ou desligar agente de IA

Campanhas

Método	Caminho	O que faz
GET	/templates	Listar templates do WhatsApp Oficial (ready: true = pode usar)
POST	/campaigns/quote	Simular o preço de uma campanha
POST	/campaigns	Criar campanha (vai para aprovação)
GET	/campaigns	Listar campanhas
GET	/campaigns/{campaign_id}	Buscar campanha (status, contadores e preço)
GET	/campaigns/{campaign_id}/recipients	Status de cada destinatário
POST	/campaigns/{campaign_id}/pause	Pausar campanha
POST	/campaigns/{campaign_id}/resume	Retomar campanha

Webhooks (gestão)

Método	Caminho	O que faz
GET	/webhooks	Listar webhooks
POST	/webhooks	Criar webhook
GET	/webhooks/{webhook_id}	Buscar webhook
PATCH	/webhooks/{webhook_id}	Atualizar webhook (URL, eventos, ativar/pausar)
DELETE	/webhooks/{webhook_id}	Excluir webhook
POST	/webhooks/{webhook_id}/test	Enviar evento de teste (ping)
GET	/webhooks/{webhook_id}/deliveries	Histórico de entregas

Objetos

Todo objeto tem o campo object (o tipo) e, quase sempre, um id (UUID):

object	Página
account	Conta
channel, channel_connection	Canais e conexões
contact	Contatos
message	Mensagens
group, group_participant	Grupos
stage	Kanban
scheduled_message	Mensagens agendadas
member	Equipe
ai_agent	Agentes de IA
template, campaign, campaign_quote, campaign_recipient	Campanhas
webhook_endpoint, webhook_delivery	Webhooks (gestão)
event	Eventos de webhook
list	Paginação

Campos sem valor vêm como null (não são omitidos). Datas seguem ISO 8601 e telefones vêm só com dígitos, com DDI.

Contrato OpenAPI

A especificação completa (OpenAPI 3.1), com todos os schemas e os payloads dos webhooks, está publicada para você importar no Postman, Insomnia, Bruno, geradores de SDK ou no ChatGPT:

openapi.yamlhttps://platform.toptalking.com.br/openapi.yaml

openapi.jsonhttps://platform.toptalking.com.br/openapi.json

Veja como usar em OpenAPI.