Documentação da API - API WhatsApp

Dicas Antibloqueio (WhatsApp)

Sugestões práticas para reduzir a chance de detecção automática ao usar automação via WhatsApp:

Evite repetir exatamente o mesmo texto; varie frases, chamadas e pontuação.
Espaçe os envios: use intervalos aleatórios e filas; não dispare em rajadas.
Não faça envios em massa. Divida lotes e distribua ao longo do tempo.
Alterne formatos: intercale textos com mídia leve (quando fizer sentido).
Simule contexto: responda a mensagens anteriores quando aplicável.
Evite links encurtados repetidos e mensagens excessivamente promocionais.
Respeite horários plausíveis e pausar ao detectar erros/bloqueios.
Revise destinatários e listas com frequência; remova números inativos.

Estas práticas são orientações gerais para uso de automação via WhatsApp e ajudam a manter baixo risco de bloqueios.

Se houver instabilidade do WhatsApp no servidor, aguarde e tente novamente. Em ambiente próprio, aumente WHATSAPP_PROTOCOL_TIMEOUT_MS e verifique recursos do container.

Endpoints e Referência

Carregando sua API Key...

Autenticação

Primeiros passos (Onboarding rápido)

1) Faça login no portal
2) No painel, clique em Conectar e leia o QR Code
3) Copie sua API Key nesta página
4) Faça um teste com /send-message
5) Acompanhe o processamento em /queue

Integração com n8n

Se você usa n8n, existe um node community “APIWHSTP” para consumir os endpoints REST. Para receber eventos, use o node Webhook do n8n e configure a URL no menu “Webhook” do portal.

Ver guia n8n Node no npm

Esta página documenta apenas os endpoints da API do Cliente (integração). Para usar os endpoints abaixo, envie sua API Key no header.

Headers

Content-Type: application/json
api-key: SUA_API_KEY_AQUI
          

Enviar Mensagem

Utilize este endpoint para enfileirar mensagens de texto via WhatsApp automaticamente através do seu sistema. O destino deve ser enviado via query: ?phone=... (contato) ou ?groupId=... (grupo). Opcionalmente, envie replyId para responder (citar) uma mensagem anterior do mesmo chat (use o campo message.id recebido no webhook).

Recomendação de performance: em cenários de alto volume, valide previamente os números com GET /check-whatsapp e evite enviar para números sem WhatsApp. Isso reduz processamento e tráfego desnecessário. O endpoint de verificação usa cache (por conta + telefone) por alguns minutos. Em caso de timeout na validação no momento do envio, o sistema pode enfileirar com <digits>@c.us para não bloquear sua requisição; se o envio falhar por número inválido, o cache é atualizado como negativo.

POST /send-message

Query Params (destino)

phone: string (contato)
groupId: string (grupo)
Regra: informe apenas um dos dois.
          

Body (JSON)

{
    "message": "Olá! Esta é uma mensagem automática enviada via API.",
    "replyId": "false_5511999999999@c.us_3EB0..."
}
          

Exemplo de uso (cURL)

curl -X POST "https://apiwhstp.com/send-message?phone=5511999999999" \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "message": "Teste de envio via API"
  }'
          

Respostas

202 Accepted: Mensagem enfileirada (retorna o id da fila).
400 Bad Request: Parâmetros inválidos ou telefone incorreto.
401 Unauthorized: API Key não fornecida.
403 Forbidden: API Key inválida.
409 Conflict: Sessão do WhatsApp não conectada.
500 Internal Server Error: Falha no processamento.

Exemplo de Sucesso (enfileirado)

{
    "status": "queued",
    "id": "2f6a7a73-5c6b-4e7b-9f51-7d77d5d7b6c3"
}
          

Exemplo de Erro

{
    "error": "Sessão do WhatsApp não conectada"
}
          

Enviar Lista Interativa

Envie uma lista interativa do WhatsApp com botão, seções e itens. O destino deve ser enviado via query: ?phone=... (contato) ou ?groupId=... (grupo). Campos obrigatórios: buttonText, sections e um destino via query. text (ou message) é opcional.

POST /send-list

Query Params (destino)

phone: string (contato)
groupId: string (grupo)
Regra: informe apenas um dos dois.
          

Body (JSON)

{
  "text": "Escolha uma opção",
  "title": "Título da Lista",
  "footer": "Rodapé da mensagem",
  "buttonText": "Clique aqui",
  "sections": [
    {
      "title": "Menu principal",
      "rows": [
        { "rowId": "opt_1", "title": "Opção 1", "description": "Descrição 1" },
        { "rowId": "opt_2", "title": "Opção 2", "description": "Descrição 2" }
      ]
    }
  ]
}
          

Exemplo de uso (cURL)

curl -X POST "https://apiwhstp.com/send-list?phone=5511999999999" \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "text": "Escolha uma opção",
    "title": "Título da Lista",
    "footer": "Rodapé da mensagem",
    "buttonText": "Clique aqui",
    "sections": [
      {
        "title": "Menu principal",
        "rows": [
          { "rowId": "opt_1", "title": "Opção 1", "description": "Descrição 1" }
        ]
      }
    ]
  }'
          

Respostas

202 Accepted: Lista enfileirada (retorna o id da fila).
400 Bad Request: Campos inválidos/ausentes.
401 Unauthorized: API Key não fornecida.
403 Forbidden: API Key inválida.
409 Conflict: Sessão do WhatsApp não conectada.
500 Internal Server Error: Falha no processamento.

Fila (Status e Gerenciamento)

Após enviar uma mensagem/mídia/áudio/localização, consulte a fila para acompanhar o status (queued, processing, success, error) e para deletar itens.

GET /queue

Query Params (opcional)

id: string (retorna 1 item)
status: string (ex.: queued,success)
          

Exemplo de uso (cURL) — listar tudo

curl -X GET https://apiwhstp.com/queue \
  -H "api-key: SUA_API_KEY_AQUI"
          

Exemplo de uso (cURL) — por id

curl -X GET "https://apiwhstp.com/queue?id=2f6a7a73-5c6b-4e7b-9f51-7d77d5d7b6c3" \
  -H "api-key: SUA_API_KEY_AQUI"
          

Exemplo de uso (cURL) — filtro por status

curl -X GET "https://apiwhstp.com/queue?status=queued,processing" \
  -H "api-key: SUA_API_KEY_AQUI"
          

DELETE /queue?id=<id>

Exemplo de uso (cURL) — deletar por id

curl -X DELETE "https://apiwhstp.com/queue?id=2f6a7a73-5c6b-4e7b-9f51-7d77d5d7b6c3" \
  -H "api-key: SUA_API_KEY_AQUI"
          

Verificar se um número possui WhatsApp

Verifica se um número está registrado no WhatsApp. Envie o parâmetro phone via query. O endpoint remove automaticamente caracteres especiais (ex.: +, espaços, parênteses) e considera apenas números. Resultado cacheado por 5 minutos por conta + telefone.

GET /check-whatsapp?phone=+5531999999999

Query Params

phone: string (obrigatório)

Exemplo de uso (cURL)

curl -X GET https://apiwhstp.com/check-whatsapp?phone=+5531999999999 \
  -H "api-key: SUA_API_KEY_AQUI"
          

Respostas

200 OK: Retorna isWhatsApp como true ou false.
400 Bad Request: Parâmetro inválido.
401 Unauthorized: API Key não fornecida.
403 Forbidden: API Key inválida.
409 Conflict: WhatsApp do cliente não está conectado.
500 Internal Server Error: Falha no processamento.

Exemplo de Sucesso

{
  "ok": true,
  "phone": "5531999999999",
  "isWhatsApp": true,
  "cached": false
}
          

Enviar Mídia (Imagem, Vídeo, Áudio, Documento)

Envie arquivos de mídia fornecendo o conteúdo em Base64 no formato Data URI (ex.: data:image/png;base64,...). O envio é sempre realizado como anexo (inclusive áudio). Para áudio, use preferencialmente audio/mpeg (mp3), audio/mp4 (m4a) ou audio/ogg. WAV (audio/wav) não é suportado. Para enviar áudio como voz/PTT, use o endpoint /send-audio. Destino via query: ?phone=... ou ?groupId=....

POST /send-media

Query Params (destino)

phone: string (contato)
groupId: string (grupo)
Regra: informe apenas um dos dois.
          

Body (JSON)

{
    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA...",
    "caption": "Legenda (opcional)",
    "filename": "imagem.png"
}
          

Exemplo de uso (cURL) — contato

curl -X POST "https://apiwhstp.com/send-media?phone=5511999999999" \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA...",
    "caption": "Legenda (opcional)",
    "filename": "imagem.png"
  }'
          

Exemplo de uso (cURL) — grupo

curl -X POST "https://apiwhstp.com/send-media?groupId=1203630234@g.us" \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA...",
    "caption": "Legenda (opcional)",
    "filename": "imagem.png"
  }'
          

O campo base64 deve obrigatoriamente estar no formato Data URI (ex.: data:image/png;base64,...) para que o tipo de mídia seja identificado automaticamente. Limite de payload: 100MB.

Respostas

202 Accepted: Mídia enfileirada (retorna o id da fila).
400 Bad Request: Parâmetros inválidos ou telefone incorreto.
401 Unauthorized: API Key não fornecida.
403 Forbidden: API Key inválida.
409 Conflict: Sessão do WhatsApp não conectada.
500 Internal Server Error: Falha no processamento.

Exemplo de Sucesso (enfileirado)

{
  "status": "queued",
  "id": "2f6a7a73-5c6b-4e7b-9f51-7d77d5d7b6c3"
}
          

Enviar Áudio como Voz/PTT

Envie um áudio OGG/Opus no formato Data URI (data:audio/ogg;base64,...); o sistema valida o tipo e envia como voz/PTT. Destino via query: ?phone=... ou ?groupId=....

POST /send-audio

Query Params (destino)

phone: string (contato)
groupId: string (grupo)
Regra: informe apenas um dos dois.
          

Body (JSON)

{
    "base64": "data:audio/ogg;base64,T2dnUwACAAAAAAAAAAD..."
}
          

Exemplo de uso (cURL) — contato

curl -X POST "https://apiwhstp.com/send-audio?phone=5511999999999" \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "base64": "data:audio/ogg;base64,T2dnUwACAAAAAAAAAAD..."
  }'
          

Exemplo de uso (cURL) — grupo

curl -X POST "https://apiwhstp.com/send-audio?groupId=1203630234@g.us" \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "base64": "data:audio/ogg;base64,T2dnUwACAAAAAAAAAAD..."
  }'
          

Requisitos: base64 deve iniciar com data:audio/ogg;base64, (OGG/Opus). Se não for áudio válido, a API retorna erro 400. Limite de payload: 100MB. Este endpoint envia sempre como voz/PTT.

Respostas

202 Accepted: Áudio enfileirado (retorna o id da fila).
400 Bad Request: Parâmetros inválidos ou telefone incorreto.
401 Unauthorized: API Key não fornecida.
403 Forbidden: API Key inválida.
409 Conflict: Sessão do WhatsApp não conectada.
500 Internal Server Error: Falha no processamento.

Exemplo de Sucesso (enfileirado)

{
  "status": "queued",
  "id": "2f6a7a73-5c6b-4e7b-9f51-7d77d5d7b6c3"
}
          

Atendimento Humano

Gerencie o status de atendimento humano para pausar o bot.

POST /attendance-open

Inicia o atendimento humano (pausa o bot).

Body (JSON)

{
    "phone": "5511888888888",        // Cliente
    "message": "Cliente solicitou atendimento" // Opcional: notifica equipe
}
          

POST /attendance-close

Encerra o atendimento humano (retoma o bot).

Body (JSON)

{
    "phone": "5511888888888"
}
          

GET /attendance

Lista números em atendimento humano. Se enviar ?phone=, retorna apenas se o número está em atendimento (true/false).

Exemplo de uso (cURL) — listar

curl -X GET https://apiwhstp.com/attendance \
  -H "api-key: SUA_API_KEY_AQUI"
          

Exemplo de uso (cURL) — checar um número

curl -X GET "https://apiwhstp.com/attendance?phone=+55 (11) 99999-9999" \
  -H "api-key: SUA_API_KEY_AQUI"
          

Respostas

Listar

{
  "numbers": ["5511888888888"]
}
          

Checar

{
  "phone": "5511999999999",
  "inAttendance": false
}
          

Enviar Localização

Envie uma localização geográfica (latitude e longitude). Destino via query: ?phone=... ou ?groupId=....

POST /send-location

Query Params (destino)

phone: string (contato)
groupId: string (grupo)
Regra: informe apenas um dos dois.
          

Body (JSON)

{
    "latitude": "-23.550520",
    "longitude": "-46.633308",
    "description": "São Paulo - SP"
}
          

Exemplo de uso (cURL) — contato

curl -X POST "https://apiwhstp.com/send-location?phone=5511999999999" \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "latitude": "-23.550520",
    "longitude": "-46.633308",
    "description": "São Paulo - SP"
  }'
          

Exemplo de uso (cURL) — grupo

curl -X POST "https://apiwhstp.com/send-location?groupId=1203630234@g.us" \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "latitude": "-23.550520",
    "longitude": "-46.633308",
    "description": "São Paulo - SP"
  }'
          

Respostas

202 Accepted: Localização enfileirada (retorna o id da fila).
400 Bad Request: Parâmetros inválidos ou telefone incorreto.
401 Unauthorized: API Key não fornecida.
403 Forbidden: API Key inválida.
409 Conflict: Sessão do WhatsApp não conectada.
500 Internal Server Error: Falha no processamento.

Exemplo de Sucesso (enfileirado)

{
  "status": "queued",
  "id": "2f6a7a73-5c6b-4e7b-9f51-7d77d5d7b6c3"
}
          

Listar Grupos

Recupere a lista de grupos onde seu WhatsApp está inserido para obter os IDs. Suporta limite de resultados e usa cache com validade de aproximadamente 5 minutos para acelerar chamadas subsequentes. Em caso de timeout, quando houver um cache anterior disponível, a API retorna o último resultado com o marcador stale: true. Ajuste o tempo de espera via variável GROUPS_TIMEOUT_MS.

GET /groups?limit=100

Exemplo de uso (cURL)

curl -X GET https://apiwhstp.com/groups?limit=100 \
  -H "api-key: SUA_API_KEY_AQUI"
          

POST /groups/cache/clear

Limpa o cache de grupos associado à sua conta.

Exemplo de uso (cURL)

curl -X POST https://apiwhstp.com/groups/cache/clear \
  -H "api-key: SUA_API_KEY_AQUI"
          

Resposta

{
  "message": "Cache de grupos limpo com sucesso",
  "account": "5511...",
  "cleared": true
}
          

Webhook — Configuração

Defina para onde as mensagens recebidas serão encaminhadas.

GET /api/webhook

Exemplo de uso (cURL)

curl -X GET https://apiwhstp.com/api/webhook \
  -H "api-key: SUA_API_KEY_AQUI"
          

POST /api/webhook

Body

{
  "url": "https://seu-endpoint",
  "authHeaderName": "API-KEY",
  "authHeaderValue": "valor"
}
          

Exemplo de uso (cURL)

curl -X POST https://apiwhstp.com/api/webhook \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "url": "https://seu-endpoint",
    "authHeaderName": "API-KEY",
    "authHeaderValue": "valor"
  }'
          

DELETE /api/webhook

Exemplo de uso (cURL)

curl -X DELETE https://apiwhstp.com/api/webhook \
  -H "api-key: SUA_API_KEY_AQUI"
          

Webhook — Grupos (Filtro)

Por padrão, mensagens recebidas em grupos não são encaminhadas para o webhook. Para receber mensagens de um grupo específico, habilite-o nesta seção.

GET /api/group-webhook

Lista os grupos com webhook habilitado para a sua conta.

Exemplo de uso (cURL)

curl -X GET https://apiwhstp.com/api/group-webhook \
  -H "api-key: SUA_API_KEY_AQUI"
          

Resposta

{
  "preferences": {
    "1203630234@g.us": true
  }
}
          

PUT /api/group-webhook

Habilita ou desabilita o encaminhamento de mensagens de um grupo para o webhook.

Body (JSON)

{
  "groupId": "1203630234@g.us",
  "enabled": true
}
          

Exemplo de uso (cURL)

curl -X PUT https://apiwhstp.com/api/group-webhook \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "groupId": "1203630234@g.us",
    "enabled": true
  }'
          

Resposta

{
  "ok": true
}
          

200 OK: Preferência atualizada.
400 Bad Request: groupId ausente ou inválido.
401 Unauthorized: API Key não fornecida.
403 Forbidden: API Key inválida.
409 Conflict: Número do WhatsApp não vinculado ao usuário.

Equipe (Staff)

Gerencie membros da sua equipe de atendimento. Ao adicionar/remover um número, o sistema envia uma mensagem automática para avisar o contato.

Autenticação: api-key.

GET /staff

Exemplo de uso (cURL)

curl -X GET https://apiwhstp.com/staff \
  -H "api-key: SUA_API_KEY_AQUI"
          

POST /staff

Adiciona um número como staff e envia uma mensagem de confirmação via WhatsApp.

Body (JSON)

{
  "phone": "5511999999999"
}
          

Resposta

{
  "ok": true,
  "phone": "5511999999999"
}
          

Exemplo de uso (cURL)

curl -X POST https://apiwhstp.com/staff \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "phone": "5511999999999"
  }'
          

200 OK: Staff adicionado.
400 Bad Request: phone inválido/ausente.
401 Unauthorized: Não autenticado.
409 Conflict: WhatsApp do cliente não está conectado.
500 Internal Server Error: Falha ao enviar mensagem de cadastro.

DELETE /staff

Remove um número da staff. Se o WhatsApp estiver conectado, o contato recebe uma mensagem de remoção.

Body (JSON)

{
  "phone": "5511999999999"
}
          

Resposta

{
  "ok": true,
  "phone": "5511999999999"
}
          

Exemplo de uso (cURL)

curl -X DELETE https://apiwhstp.com/staff \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "phone": "5511999999999"
  }'
          

200 OK: Staff removido.
400 Bad Request: phone inválido/ausente.
401 Unauthorized: Não autenticado.

POST /staff-message

Envia uma mensagem de aviso para todos os números cadastrados como staff.

Body (JSON)

{
  "message": "Aviso geral"
}
          

Resposta

{
  "ok": true,
  "account": "5511999999999",
  "sent": 2,
  "total": 2
}
          

Exemplo de uso (cURL)

curl -X POST https://apiwhstp.com/staff-message \
  -H "Content-Type: application/json" \
  -H "api-key: SUA_API_KEY_AQUI" \
  -d '{
    "message": "Aviso geral"
  }'
          

200 OK: Mensagem enviada para a staff.
400 Bad Request: message ausente.
401 Unauthorized: API Key não fornecida.
403 Forbidden: API Key inválida.
409 Conflict: WhatsApp não conectado ou sem staff cadastrada.