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 }
jobIdidentifica o envio na fila.scheduledAté quando o envio está previsto, em milissegundos unix.positioné o lugar da mensagem na fila do número.
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:
media: imagem, vídeo, áudio, documento ou figurinha a partir de uma URL https. Veja envio de mídia.location: uma localização com latitude, longitude e nome.template: uma mensagem salva com variáveis, enviada pelo nome.
{ "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:
| Evento | Quando chega |
|---|---|
message.delivery | O status mudou: sent, delivered, read ou failed, com o messageId e o clientRef |
message.send_failed | Um envio com clientRef não vai acontecer, com o motivo (por exemplo, not_on_whatsapp) |
message.outgoing | A 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.
Outros recursos
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 breveHoje 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.