Início rápido

Em cinco minutos você vai gerar uma chave, confirmar que ela funciona e mandar uma mensagem de WhatsApp pela API.

Antes de começar: você precisa ser administrador da organização na TopTalking e ter um WhatsApp conectado — no painel (Configurações → Conexões) ou pela própria API (veja abaixo).

1. Gere a chave de API

Abra o painel em Configurações → Desenvolvedor.
No cartão Chaves de API, clique em Criar chave.
Dê um nome que diga quem vai usar a chave (ex.: “Integração do site”), escolha o acesso Acesso total e a validade.
Copie a chave (tt_live_...) e guarde em um lugar seguro. Ela é mostrada uma única vez.

2. Guarde a chave numa variável de ambiente

Nunca cole a chave direto no código. Use uma variável de ambiente (no servidor, um “secret”):

macOS / Linux
Windows (PowerShell)

export TOPTALKING_API_KEY="tt_live_SUA_CHAVE"

$env:TOPTALKING_API_KEY = "tt_live_SUA_CHAVE"

3. Teste a chave com `GET /me`

curl https://platform.toptalking.com.br/v1/me \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

// Node.js 18+ (rode com: node teste.mjs)
const res = await fetch('https://platform.toptalking.com.br/v1/me', {
  headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
});

console.log(res.status, await res.json());

import os
import requests

res = requests.get(
    "https://platform.toptalking.com.br/v1/me",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    timeout=30,
)
print(res.status_code, res.json())

Se a chave estiver certa, a resposta é 200 com os dados da organização e da chave:

{
  "object": "account",
  "organization": {
    "id": "e044a615-e879-44bb-8510-948b10b5e93c",
    "name": "Loja Aurora"
  },
  "api_key": {
    "id": "508a23eb-5e24-4997-b928-3fce4f0f5593",
    "name": "Integração do site",
    "prefix": "tt_live_a1b2c3d4",
    "access": "full",
    "created_at": "2026-11-11T13:02:11Z"
  },
  "rate_limit": {
    "limit": 120,
    "remaining": 119,
    "reset_at": "2026-11-11T14:31:00Z"
  }
}

Recebeu 401? Confira se o cabeçalho está exatamente como Authorization: Bearer tt_live_... (com a palavra Bearer e um espaço). Veja Erros.

4. Envie a sua primeira mensagem

Use o seu próprio número para testar. Informe o telefone com DDI e DDD:

curl https://platform.toptalking.com.br/v1/messages \
  -H "Authorization: Bearer $TOPTALKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: teste-primeira-mensagem-001" \
  -d '{
    "to": "5511999998888",
    "text": "Olá! Esta é a minha primeira mensagem pela API da TopTalking. 🚀"
  }'

const res = await fetch('https://platform.toptalking.com.br/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'teste-primeira-mensagem-001',
  },
  body: JSON.stringify({
    to: '5511999998888',
    text: 'Olá! Esta é a minha primeira mensagem pela API da TopTalking. 🚀',
  }),
});

const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log('Mensagem enviada:', body.id, body.status);

import os
import requests

res = requests.post(
    "https://platform.toptalking.com.br/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}",
        "Idempotency-Key": "teste-primeira-mensagem-001",
    },
    json={
        "to": "5511999998888",
        "text": "Olá! Esta é a minha primeira mensagem pela API da TopTalking. 🚀",
    },
    timeout=30,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print("Mensagem enviada:", body["id"], body["status"])

Resposta 201:

{
  "id": "03ab9a84-86b0-4a1c-a9b2-bbfa205cc52e",
  "object": "message",
  "contact_id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
  "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
  "direction": "outbound",
  "type": "text",
  "text": "Olá! Esta é a minha primeira mensagem pela API da TopTalking. 🚀",
  "media": null,
  "status": "sent",
  "error": null,
  "reply_to_id": null,
  "reaction": null,
  "sender_name": null,
  "transcript": null,
  "created_at": "2026-11-11T14:30:12Z",
  "edited_at": null
}

Pronto: a mensagem chegou no WhatsApp e já aparece no chat do painel. Se o número ainda não era contato, o contato foi criado e a conversa está na caixa de entrada.

Próximos passos

Conecte mais números de WhatsApp pela API: Canais e conexões.
Receba as respostas dos clientes com webhooks.
Veja tudo o que dá para fazer na Referência da API.
Vai integrar com Lovable, Claude, Cursor ou ChatGPT? Comece por Integrar com IA.
Antes de colocar em produção, leia Boas práticas no WhatsApp.