Claude

O Claude pode trabalhar com a TopTalking de dois jeitos:

Operar a conta pelo servidor MCP: consultar conversas, mover cards, enviar mensagens (com a sua aprovação).
Escrever código de integração com a API REST, lendo esta documentação.

Claude Code

1. Conecte o MCP

claude mcp add --transport http toptalking https://platform.toptalking.com.br/mcp --header "Authorization: Bearer tt_live_SUA_CHAVE"

Detalhes, escopos e permissões em MCP no Claude Code. Para o Claude Code só escrever código, o MCP é opcional — mas ajuda: ele pode consultar as etapas reais do seu Kanban e testar a chave.

2. Adicione as regras ao `CLAUDE.md`

Cole no CLAUDE.md do seu projeto. O Claude Code lê esse arquivo em toda sessão:

## Integração com a TopTalking (WhatsApp + CRM)

- Documentação completa: https://platform.toptalking.com.br/llms-full.txt
  Contrato OpenAPI 3.1: https://platform.toptalking.com.br/openapi.yaml
  Consulte antes de usar um endpoint. Não invente endpoints nem campos.
- API REST: base `https://platform.toptalking.com.br/v1`, JSON, cabeçalho `Authorization: Bearer <chave>`.
- A chave vem SEMPRE da variável de ambiente `TOPTALKING_API_KEY`. Nunca escreva a chave no código, em testes,
  em logs, em fixtures ou em commits. Nunca chame a API a partir de código que roda no navegador (a API não tem CORS).
- Envios (`POST /messages`, `POST /scheduled-messages`) sempre com `Idempotency-Key` derivada do ID da operação
  (ex.: `pedido-<id>-despachado`), para retentativas não duplicarem mensagens.
- Erros: `{ "error": { "type", "code", "message", "param", "request_id" } }`. Trate pelo `code`.
  Em 429, espere `Retry-After` segundos. Não repita erros 4xx. Registre o `request_id` nos logs.
- Listas: paginação por cursor (`has_more`, `next_cursor` → `?cursor=`), `limit` de 1 a 100.
- Telefones: DDI + DDD, só dígitos (ex.: `5511999998888`).
- Webhooks: validar `X-TopTalking-Signature` (`t=<unix>,v1=<hex>`; v1 = HMAC-SHA256 hex de `<t>.<corpo cru>`
  com `TOPTALKING_WEBHOOK_SECRET`), tolerância de 300 s, comparação em tempo constante, responder 2xx em até 10 s,
  deduplicar pelo `id` do evento.
- Testes automatizados nunca chamam a API real para enviar mensagens: use mocks.
- Nada de envio em massa (risco de banimento do número de WhatsApp).
- Ferramentas MCP `toptalking` que enviam mensagens ou alteram contatos: só use quando eu pedir explicitamente.

3. Peça a integração

Leia https://platform.toptalking.com.br/llms-full.txt e as regras da TopTalking no CLAUDE.md.

Crie um módulo de integração com a API da TopTalking neste projeto:

1. Um cliente pequeno (sem dependências novas, usando fetch) com:
   - request(method, path, { body, idempotencyKey, query }) que usa https://platform.toptalking.com.br/v1,
     o cabeçalho Authorization: Bearer ${process.env.TOPTALKING_API_KEY} e lança um erro tipado com status, code,
     message e requestId quando a resposta não for 2xx. Em 429, espere Retry-After e tente de novo até 3 vezes.
   - Funções: getMe(), listStages(), findContactByPhone(phone) (GET /contacts?phone=),
     upsertContact({ phone, name, email, stageId }), moveContact(contactId, stageId),
     sendMessage({ to | contactId, text, media, idempotencyKey }), listAllContacts() (percorre todas as páginas com cursor).
2. Uma rota POST /webhooks/toptalking que valida X-TopTalking-Signature com o corpo cru
   (TOPTALKING_WEBHOOK_SECRET, tolerância de 300 s, comparação em tempo constante), responde 200 rápido
   e despacha o evento por tipo (message.received, contact.stage_changed, ping), ignorando duplicados pelo id do evento.
3. Testes unitários com fetch mockado, incluindo o vetor de teste da assinatura que está na documentação.
4. Atualize o .env.example com TOPTALKING_API_KEY= e TOPTALKING_WEBHOOK_SECRET= (sem valores).

Antes de escrever, mostre o plano e os arquivos que vai criar.

Claude.ai (Projetos)

No claude.ai, os Projetos guardam arquivos como conhecimento fixo. Coloque a documentação lá e todas as conversas do projeto já sabem usar a API.

Abra llms-full.txt no navegador e salve como arquivo (Ctrl+S / Cmd+S), por exemplo toptalking-llms-full.txt.
No claude.ai, crie um projeto (ex.: “Integração TopTalking”).
Em Conhecimento do projeto, envie o arquivo toptalking-llms-full.txt.

Em Instruções do projeto, cole:

Você me ajuda a integrar sistemas com a API da TopTalking (WhatsApp + CRM com Kanban).
Use APENAS o arquivo de documentação do projeto como referência: não invente endpoints, campos ou eventos.
Sempre: chamadas só pelo backend (nunca no navegador), chave em variável de ambiente TOPTALKING_API_KEY,
Idempotency-Key em envios, tratamento de erros pelo "code", validação da assinatura dos webhooks.
Responda em português do Brasil, com código completo e explicando onde cada arquivo fica.

Comece uma conversa no projeto com um pedido concreto.

Prompt de exemplo:

Tenho uma loja em Next.js (App Router) com pedidos numa tabela "orders" (id, customer_name, customer_phone, status).
Quero que, quando o status mudar para "shipped", o cliente receba no WhatsApp: "Olá, <nome>! Seu pedido #<id> saiu para entrega."

Escreva:
1. A função de servidor que envia a mensagem pela API da TopTalking (POST /messages) com Idempotency-Key "order-<id>-shipped".
2. Onde chamar essa função no fluxo de atualização do pedido.
3. O tratamento dos erros channel_unavailable, invalid_phone e rate_limit_exceeded.
4. Como configurar TOPTALKING_API_KEY na Vercel.
Use a documentação do projeto como fonte.

Claude Desktop

Para o Claude Desktop operar a conta (consultar conversas, mover cards, enviar com aprovação), conecte o MCP pelo mcp-remote: veja MCP no Claude Desktop.

Você pode combinar com um Projeto: as conversas do projeto têm a documentação, e o MCP dá acesso aos dados reais.

Usando as ferramentas da TopTalking: liste as conversas da etapa "Negociação" que não recebem mensagem há mais de 3 dias.
Para cada uma, leia as últimas 10 mensagens e sugira uma mensagem de follow-up curta e educada.
NÃO envie nada: só me mostre as sugestões para eu aprovar uma por uma.