Documentação da API do WhatsApp

Referência completa da API REST do WhatsApp. Autenticação, endpoints, webhooks, códigos de erro e exemplos de código.

Autenticação

Todas as requisições à API exigem uma chave de API enviada no cabeçalho Authorization. Sua chave de API é gerada quando você cria uma instância e pode ser encontrada no seu painel.

Authorization: Bearer YOUR_API_KEY

Requisições sem uma chave de API válida retornam um erro 401 Unauthorized. As chaves de API são vinculadas a instâncias — cada instância tem sua própria chave.

URL Base

https://api2whats.com

Todos os endpoints são relativos a esta URL base. Use apenas HTTPS — requisições HTTP são rejeitadas.

Enviar Mensagem de Texto

Envie uma mensagem de texto para um número do WhatsApp.

POST /send-text

Corpo da requisição:

{
  "to": "971501234567",
  "message": "Hello from the API!"
}

Parâmetros:

  • to (string, obrigatório) — Número de telefone do destinatário com código do país, sem + ou espaços
  • message (string, obrigatório) — Conteúdo de texto, suporta Unicode e emoji

Resposta:

{
  "success": true,
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "sent"
  }
}

Enviar Imagem

Envie uma imagem via URL ou Base64.

POST /send-image

{
  "to": "971501234567",
  "image": "https://example.com/photo.jpg",
  "caption": "Check out this product!"
}

Parâmetros:

  • to (string, obrigatório) — Número de telefone do destinatário
  • image (string, obrigatório) — URL da imagem ou string codificada em Base64
  • caption (string, opcional) — Legenda de texto abaixo da imagem

Enviar Vídeo

Envie um arquivo de vídeo.

POST /send-video

{
  "to": "971501234567",
  "video": "https://example.com/demo.mp4",
  "caption": "Product demo video"
}

Enviar Áudio

Envie um arquivo de áudio (nota de voz ou clipe de áudio).

POST /send-audio

{
  "to": "971501234567",
  "audio": "https://example.com/voice.mp3"
}

Enviar Figurinha

Envie uma imagem de figurinha (formato WebP ou PNG).

POST /send-sticker

{
  "to": "971501234567",
  "sticker": "https://example.com/sticker.webp"
}

Enviar Documento

Envie um anexo de arquivo (PDF, DOCX, XLSX, etc.).

POST /send-document

{
  "to": "971501234567",
  "document": "https://example.com/invoice.pdf",
  "filename": "invoice-march-2026.pdf"
}

Parâmetros:

  • to (string, obrigatório) — Número de telefone do destinatário
  • document (string, obrigatório) — URL do documento ou string codificada em Base64
  • filename (string, opcional) — Nome de exibição do arquivo (padrão: nome do arquivo da URL)

Enviar Localização

Envie um pin de localização geográfica.

POST /send-location

{
  "to": "971501234567",
  "latitude": 25.2048,
  "longitude": 55.2708,
  "name": "Dubai Office"
}

Configuração de Webhooks

Os webhooks permitem que seu servidor receba mensagens recebidas em tempo real. Defina sua URL de webhook via API:

POST /set-webhook

{
  "url": "https://yourserver.com/webhook"
}

Quando alguém envia uma mensagem para o seu número conectado, a API envia uma requisição POST para a sua URL:

{
  "event": "message",
  "instance": "instance_abc123",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hi, I need help",
    "timestamp": 1691234567,
    "type": "text"
  }
}

Verifique os webhooks recebidos usando o cabeçalho X-Signature incluído em cada requisição.

Gerenciamento de Instâncias

Verifique o status de conexão da sua instância do WhatsApp:

GET /instance/status

Resposta:
{
  "connected": true,
  "phone": "971501234567",
  "name": "Business Account"
}

Códigos de Erro

Código HTTPCódigo de ErroDescrição
400INVALID_PHONEO formato do número de telefone é inválido
400MISSING_FIELDCampo obrigatório ausente na requisição
401INVALID_API_KEYA chave de API é inválida ou está ausente
404INSTANCE_NOT_FOUNDA instância não existe ou não está conectada
429RATE_LIMIT_EXCEEDEDMuitas requisições, verifique o cabeçalho Retry-After
500INTERNAL_ERRORErro do servidor, tente novamente com backoff exponencial

Limites de Taxa

Os limites de taxa variam conforme o plano:

  • Basic — 100 requisições/minuto
  • Professional — 300 requisições/minuto
  • Enterprise — 1000 requisições/minuto

Ao atingir o limite, a API retorna 429 Too Many Requests com um cabeçalho Retry-After indicando quando você pode tentar novamente.

Exemplos de Código

Exemplos funcionais em PHP, Python, JavaScript e cURL estão disponíveis na nossa seção de exemplos de código. Cada exemplo é um script completo e executável.

Paginação e Limites

Ao listar recursos (instâncias, histórico de mensagens), a API suporta paginação por meio de parâmetros de consulta:

GET /messages?page=1&limit=50

Resposta:
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 342,
    "pages": 7
  }
}

O tamanho padrão da página é 50. O máximo é 100. Use os parâmetros de consulta page e limit para navegar pelos resultados.

Envio em Lote

Envie mensagens para vários destinatários em uma única chamada à API. Isso é mais eficiente do que fazer requisições individuais para cada destinatário.

POST /send-batch

{
  "messages": [
    { "to": "971501234567", "message": "Hello Ahmed!" },
    { "to": "971509876543", "message": "Hello Sara!" },
    { "to": "971501112222", "message": "Hello Omar!" }
  ]
}

O envio em lote aplica limite de taxa automaticamente. A resposta inclui o status de cada mensagem para você saber quais tiveram sucesso e quais falharam.

Diretrizes de Envio de Mídia

Ao enviar mídia, siga estas diretrizes para uma entrega ideal:

  • Images — JPEG ou PNG, máximo de 5MB via Base64, maiores via URL. Dimensões recomendadas: 1200x630 para paisagem, 600x600 para quadrado.
  • Videos — Formato MP4, máximo de 16MB. Codificação H.264 recomendada para melhor compatibilidade.
  • Documents — PDF, DOCX, XLSX, PPTX, TXT. Máximo de 100MB via URL.
  • Audio — Formato MP3 ou OGG. Máximo de 16MB.
  • Stickers — WebP ou PNG, 512x512 pixels, máximo de 500KB.
  • Locations — Coordenadas de latitude/longitude com nome e endereço opcionais.

Para codificação Base64, inclua o prefixo data URI: data:image/jpeg;base64,/9j/4AAQ.... Para URLs, certifique-se de que a URL seja publicamente acessível e retorne o cabeçalho Content-Type correto.

Variáveis de Ambiente

Armazene sua chave de API e configuração em variáveis de ambiente, não no seu código:

# .env file
WHATSAPP_API_KEY=your_api_key_here
WHATSAPP_API_BASE=https://api2whats.com
WEBHOOK_SECRET=your_webhook_secret_here

Nunca faça commit do seu arquivo .env no controle de versão. Adicione-o ao .gitignore. Use as configurações de variáveis de ambiente da sua plataforma de deploy em produção.

Versionamento

A API é versionada por meio do caminho da URL. A versão atual é v1 (a padrão). Quando introduzirmos mudanças incompatíveis, lançaremos uma nova versão e manteremos a anterior por pelo menos 12 meses.

# Current version (implicit)
https://api2whats.com/send-text

# Explicit version (future-proof)
https://api2whats.com/v1/send-text

Changelog

Mantemos um changelog público para todas as mudanças da API. Assine o feed RSS do changelog ou siga-nos no GitHub para se manter atualizado. Mudanças importantes são anunciadas por e-mail a todos os usuários registrados com pelo menos 30 dias de antecedência.

Precisa de Ajuda?

Consulte o FAQ para perguntas comuns. Para problemas específicos, entre em contato com nossa equipe de suporte. Respondemos em até 24 horas.

FAQ

Qual é o tamanho máximo da mensagem?

Mensagens de texto suportam até 4.096 caracteres. Para conteúdo mais longo, considere enviar um documento ou dividir a mensagem em vários envios.

Posso enviar mensagens para grupos?

Atualmente, a API suporta apenas mensagens 1 para 1. O envio para grupos está no nosso roadmap para uma versão futura.

Com que rapidez as mensagens são entregues?

A maioria das mensagens é entregue em 1 a 3 segundos. O tempo de entrega depende da conexão de rede do destinatário e do status do dispositivo. Mensagens para dispositivos offline são enfileiradas pelo WhatsApp e entregues quando o dispositivo ficar online.

Existe um plano gratuito?

Você pode criar uma conta e explorar o painel gratuitamente. Os planos pagos começam em US$ 9,99/mês para acesso à API e envio de mensagens. Entre em contato para acesso de teste.

O que acontece se minha chave de API for comprometida?

Revogue imediatamente a chave comprometida no seu painel e gere uma nova. Todas as sessões ativas que usam a chave antiga serão encerradas. Recomendamos rotacionar as chaves de API periodicamente e armazená-las em variáveis de ambiente.

Posso usar a API para envio em massa?

Yes, with proper rate limiting. Send messages with 2-3 second delays between them. Do not send identical messages to large groups — personalize each message. Monitor delivery rates and slow down if they drop below 90%. docspage.faq.a6.link

Página de Status

Verifique o status do nosso sistema e o uptime histórico na nossa página de status. Fornecemos atualizações em tempo real durante incidentes e publicamos post-mortems detalhados para qualquer interrupção de serviço.

Pronto para Integrar?

Crie uma conta e comece a enviar mensagens em minutos.

Comece Grátis