# TopTalking API > A TopTalking é uma plataforma brasileira de atendimento no WhatsApp com CRM (Kanban) e agentes de IA. A API REST e o servidor MCP da TopTalking permitem que sistemas e IAs enviem mensagens de WhatsApp, gerenciem contatos e o Kanban, agendem mensagens e recebam eventos por webhook. Regras essenciais para usar a API da TopTalking: - URL base da API REST: `https://platform.toptalking.com.br/v1`. Tudo em JSON (UTF-8), datas em ISO 8601 e IDs em UUID. - Autenticação: cabeçalho `Authorization: Bearer tt_live_...` (também aceita `X-Api-Key: tt_live_...`). A chave é criada por um administrador da organização no painel, em Configurações → Desenvolvedor (https://toptalking.com.br/configuracoes/desenvolvedor). Chaves "Somente leitura" recebem 403 `read_only_key` em qualquer método que não seja GET. - NUNCA coloque a chave em código que roda no navegador (React, Vue, HTML, app mobile). A API não tem CORS de propósito. Chame sempre de um backend: servidor próprio, Supabase Edge Function (apps do Lovable), rota de API do Next.js, n8n, Make ou Zapier. Guarde a chave como segredo (ex.: `TOPTALKING_API_KEY`). - Limite de 120 requisições por minuto por chave (cabeçalhos `X-RateLimit-*`; em 429, respeite `Retry-After`). - Erros: `{ "error": { "type", "code", "message", "param", "request_id" } }`. Trate pelo `code`. - Listas usam paginação por cursor: `{ "object": "list", "data": [...], "has_more", "next_cursor" }`; envie `cursor=` e `limit` (1–100, padrão 20). - Envie `Idempotency-Key` em requisições POST (principalmente `POST /messages`) para que retentativas não dupliquem mensagens. - Telefones com DDI e DDD (ex.: `5511999998888`). Números brasileiros sem `55` recebem o `55`. - Conectar um WhatsApp pela API: `POST /v1/channels` (201, devolve `channel.id` e `qr_code`, uma imagem PNG em data URL para usar direto em ``; pode vir `null` nos primeiros segundos). Depois consulte `GET /v1/channels/{channel_id}/qr` a cada 3–5 s (o QR Code muda a cada ~20–40 s) até `status` = `connected`, ou assine o webhook `channel.status_updated`. Sem câmera: `POST /v1/channels/{channel_id}/connect` com `{ "phone": "5511..." }` devolve `pairing_code`. Canal `disconnected`: gere outro QR com `POST /v1/channels/{channel_id}/connect` (não crie outro canal; criar além do limite do plano dá 422 `limit_reached`). A tela que mostra o QR deve chamar o SEU backend, nunca a API direto. - Grupos do WhatsApp são conversas: o `id` de `GET /v1/groups` é um `contact_id`. Leia com `GET /v1/contacts/{id}/messages` e envie com `POST /v1/messages` `{ "contact_id": "", "text": "..." }`. - Campanhas (envio em massa) usam o WhatsApp Oficial (API da Meta), que é conectado no painel e não é um canal de `/channels`. Precisam de um template com `ready: true` (`GET /v1/templates`) e passam por aprovação da TopTalking: `POST /v1/campaigns` cria em `pending_approval` → `approved` → `running` → `completed` (ou `changes_requested`, veja `review_notes`). Até 5.000 destinatários por requisição; `variables` de cada um com exatamente `variables_count` itens. Sem WhatsApp Oficial: 422 `channel_unavailable`. Nunca use `POST /messages` em loop para disparos em massa. - Webhooks: POST JSON assinado com `X-TopTalking-Signature: t=,v1=`, onde v1 = HMAC-SHA256 (chave = secret `whsec_...`) de `.`. Responda 2xx em até 10 s. - Servidor MCP (Streamable HTTP): `https://platform.toptalking.com.br/mcp`, com o mesmo cabeçalho `Authorization: Bearer tt_live_...`. - Contrato OpenAPI 3.1: https://platform.toptalking.com.br/openapi.yaml (também em /openapi.json). - Só envie mensagens para quem pediu ou aceitou recebê-las (opt-in). Disparos em massa e mensagens não solicitadas podem fazer o WhatsApp banir o número. ## Documentation Sets - [Abridged documentation](https://platform.toptalking.com.br/llms-small.txt): a compact version of the documentation for TopTalking API, with non-essential content removed - [Complete documentation](https://platform.toptalking.com.br/llms-full.txt): the full documentation for TopTalking API - [API REST](https://platform.toptalking.com.br/_llms-txt/api-rest.txt): autenticação, erros, limites, paginação, idempotência e a referência completa dos endpoints - [Webhooks](https://platform.toptalking.com.br/_llms-txt/webhooks.txt): eventos, payloads, verificação da assinatura e entregas - [Servidor MCP](https://platform.toptalking.com.br/_llms-txt/servidor-mcp.txt): ferramentas MCP e configuração no Claude, Cursor, VS Code e Windsurf - [Guias de IA](https://platform.toptalking.com.br/_llms-txt/guias-de-ia.txt): passo a passo e prompts prontos para Lovable, Claude, Cursor, ChatGPT, Bolt, v0, Replit, n8n, Make e Zapier ## Notes - The complete documentation includes all content from the official documentation - The content is automatically generated from the same source as the official documentation ## Optional - [OpenAPI (YAML)](https://platform.toptalking.com.br/openapi.yaml): contrato OpenAPI 3.1 completo da API, incluindo os payloads dos webhooks - [OpenAPI (JSON)](https://platform.toptalking.com.br/openapi.json): o mesmo contrato em JSON - [Painel da TopTalking](https://toptalking.com.br): onde o cliente conecta o WhatsApp e cria as chaves de API