Pular para o conteúdo
apiwpp
Recurso

Envio de mensagens de texto pela API

Envie mensagens de WhatsApp com uma chamada HTTP: a apiwpp coloca o envio na fila do número, responde 202 na hora e conta o resultado pelo webhook.

Atualizado em

Enviar uma mensagem de WhatsApp pela apiwpp é uma chamada HTTP: você informa o número de destino e o texto, e a API cuida do resto. O que muda em relação a uma API que "dispara na hora" é que cada número tem uma fila. A mensagem entra na fila, sai no ritmo que protege o número de bloqueios, e o resultado chega ao seu servidor pelo webhook.

Esse desenho deixa o seu código simples. A chamada responde em milissegundos, você não precisa segurar conexões abertas esperando o WhatsApp, e o seu sistema não precisa implementar sozinho as pausas entre envios.

A chamada de envio

curl -s -X POST "https://api.apiwpp.com/connections/$CONNECTION_ID/send" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"to": "5511988887777", "message": "Olá! Sua consulta está confirmada.", "clientRef": "consulta-1234"}'

A resposta é 202 Accepted, na hora:

{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }

A chave de API precisa do escopo messages:send, e a conexão precisa estar open. Se o número estiver desconectado, a resposta é 400 com o status atual, e nada entra na fila.

O mesmo envio em Node.js, com fetch:

const response = await fetch(`https://api.apiwpp.com/connections/${connectionId}/send`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.APIWPP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '5511988887777',
    message: 'Seu pedido saiu para entrega.',
    clientRef: 'pedido-1234',
  }),
})

if (response.status === 429) {
  const wait = response.headers.get('Retry-After')
  // Tente de novo depois de `wait` segundos.
} else if (!response.ok) {
  const { error } = await response.json()
  throw new Error(error)
}

O destinatário: só dígitos, e a API resolve o resto

O campo to recebe o número com código do país e DDD, só dígitos: 5511988887777. Antes de enviar, a apiwpp pergunta ao WhatsApp em qual endereço interno (o JID) aquele número está registrado, e envia para ele.

Isso resolve um problema clássico do Brasil: o nono dígito. Contas antigas foram registradas sem o 9 e continuam assim no WhatsApp. Quem monta o endereço na mão erra para esses contatos; na apiwpp, a mensagem chega mesmo quando você manda o número com o nono dígito. A API nunca inclui nem remove o dígito por conta própria: ela pergunta ao WhatsApp.

Um número que não está no WhatsApp falha na hora, sem novas tentativas. Para conferir uma lista antes de enviar, POST /connections/{id}/contacts/check verifica até 100 números de uma vez. E se você já tem o endereço, to também aceita um JID, usado como veio.

"Digitando…" antes de cada texto

Uma conversa humana não recebe um parágrafo inteiro no mesmo segundo. Por isso, cada mensagem de texto mostra o indicador de "digitando…" ao destinatário antes de chegar. O tempo padrão é de 1500 milissegundos, e você controla com typingDelay:

{ "to": "5511988887777", "message": "Seu pedido saiu para entrega.", "typingDelay": 3000 }

Use um valor maior para mensagens longas: fica mais natural para quem lê.

Outros tipos de conteúdo na mesma rota

A mesma chamada envia outros conteúdos. Em vez de message, mande um destes campos:

{ "to": "5511988887777", "location": { "latitude": -23.5614, "longitude": -46.6559, "name": "Loja Paulista" } }

Sem nenhum desses campos, a resposta é 400.

A fila protege o número

A fila de cada número segue um ritmo que reduz o risco de o WhatsApp restringir a conta. Os padrões são 3 mensagens por minuto, 60 por hora e 200 por dia, com um intervalo aleatório de 3 a 8 segundos entre envios e pelo menos 30 segundos entre duas mensagens para a mesma pessoa. Números recém-conectados passam por um aquecimento de 14 dias com limites menores.

Destinatários novos (que não trocaram mensagens com o número nos últimos 28 dias) têm um teto de 100 a cada 24 horas. Passando dele, o envio responde 429 new_recipient_cap_reached com o cabeçalho Retry-After, e nada entra na fila. Contatos conhecidos nunca são barrados por esse teto.

Dentro desses limites, as mensagens são ilimitadas: a apiwpp cobra por número conectado, não por mensagem. Para ver o estado da fila, GET /connections/{id}/queue mostra os envios pendentes, os limites atuais e quanto já foi usado; DELETE /connections/{id}/queue/{jobId} cancela um envio que ainda não saiu.

O resultado chega pelo webhook

Como o envio é assíncrono, o que aconteceu com cada mensagem chega ao seu servidor pelos webhooks do projeto:

EventoQuando chega
message.deliveryO status mudou: sent, delivered, read ou failed, com o messageId e o clientRef
message.send_failedUm envio com clientRef não vai acontecer, com o motivo (por exemplo, not_on_whatsapp)
message.outgoingA mensagem saiu; opcional, ativado por projeto

Mande sempre um clientRef com o identificador do seu sistema (o id do pedido, da consulta, da fatura). Ele volta em todos esses eventos e ainda torna o envio idempotente: repetir a mesma chamada com o mesmo clientRef devolve o job original com "duplicate": true, sem enviar duas vezes.

Para o passo a passo com código, leia o tutorial enviar mensagem de WhatsApp com Node.js, ou volte para todos os recursos da apiwpp.

Perguntas frequentes

Por que a API responde 202 e não envia na hora?

Porque cada número tem uma fila que respeita um ritmo seguro de envio. A resposta 202 confirma que a mensagem foi aceita e diz quando o envio está previsto (scheduledAt) e a posição na fila. O resultado chega depois pelo webhook message.delivery.

Preciso tratar o nono dígito no meu sistema?

Não. Mande o número com código do país e DDD, só dígitos. A apiwpp consulta o WhatsApp para descobrir em qual endereço o número está registrado, então contas antigas sem o nono dígito também recebem.

Existe limite de mensagens por mês?

Não há cota de mensagens nem cobrança por mensagem. O limite é o ritmo da fila de cada número (por padrão 3 por minuto, 60 por hora e 200 por dia), que existe para proteger o número de bloqueios.

Como evito enviar a mesma mensagem duas vezes?

Envie um clientRef único para cada mensagem. Se a sua requisição for repetida por um timeout ou uma nova tentativa, a API devolve o job original com "duplicate": true e não coloca nada novo na fila.

Todos: Recursos →

Imagem, vídeo, áudio, documento e figurinha saem pela mesma rota de envio, a partir de uma URL https pública. Áudio pode ir como mensagem de voz, documento leva nome e legenda, e a mídia recebida chega no webhook.

Cada evento do número chega no seu servidor com um POST assinado com HMAC-SHA256. A entrega é feita pelo menos uma vez, com novas tentativas, registro de cada entrega e reenvio.

Grupos

Em breve

Hoje a API lista os grupos de que o número participa, entrega as mensagens de grupo no webhook e avisa quando o número entra, sai ou quando um grupo muda. Criar grupos e gerenciar participantes está em desenvolvimento para o PRO.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.