Enviar mensagens
Texto, mídia, localização e templates pela fila de cada número, com reações, verificação de contatos e os eventos que contam o que houve com cada envio.
POST /connections/{id}/send não envia na hora: ele coloca a mensagem na fila do número e responde 202 com o job. A fila envia no ritmo que protege o número de bloqueios (veja Limites de envio), e o resultado chega pelos webhooks. A chave precisa do escopo messages:send.
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": "pedido-1234"}'const response = await fetch(`https://api.apiwpp.com/connections/${process.env.CONNECTION_ID}/send`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '5511988887777',
message: 'Olá! Sua consulta está confirmada.',
clientRef: 'pedido-1234',
}),
});
if (response.status !== 202 && response.status !== 200) {
throw new Error(`Envio recusado: ${response.status} ${await response.text()}`);
}
const { jobId, scheduledAt, position } = await response.json();{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }jobId identifica o envio na fila, scheduledAt é quando ele está previsto (unix em milissegundos) e position é o lugar dele na fila do número. Repetir a requisição com o mesmo clientRef na mesma conexão não enfileira de novo: a resposta é 200 com o job original e "duplicate": true (veja Idempotência). Mande sempre um clientRef: ele também volta nos eventos da mensagem.
A conexão precisa estar open. Em outro status, a resposta é 400 com { "error": "Connection not ready (status: close)" }.
O destinatário
to é o número com o código do país na frente, como 5511988887777: só os dígitos são lidos. Antes de enviar, a apiwpp pergunta ao WhatsApp em qual endereço (JID) aquele número está registrado e envia para ele. Assim, contas antigas registradas sem o nono dígito recebem a mensagem mesmo quando você manda o número com ele; a apiwpp nunca inclui nem remove o nono dígito por conta própria.
to também aceita um JID, usado como veio:
| Formato | Destinatário |
|---|---|
[email protected] | Uma pessoa, pelo telefone |
…@lid | Uma pessoa identificada só pelo LID (o jid de um evento, veja LID e contact.resolved) |
…@g.us | Um grupo em que o número está (veja Listar grupos) |
…@broadcast, …@newsletter | Uma lista de transmissão ou um canal |
Qualquer outra coisa é recusada na hora com 400 e error: "invalid_recipient". Um número que não está no WhatsApp é aceito na fila, mas falha no envio, sem novas tentativas: com clientRef, chega um message.send_failed com reason: not_on_whatsapp. Para conferir antes, veja Verificar números e perfis.
Tipos de mensagem
O conteúdo vai em message, media, location ou template. Sem nenhum deles, a resposta é 400 com { "error": "message, media, location, or template is required" }. Se vier mais de um, location vale sozinho; com media, o texto de message vira a legenda quando media.caption não vem.
Antes de cada envio, o contato vê "digitando…" por typingDelay milissegundos (padrão: 1500).
Texto
{ "to": "5511988887777", "message": "Seu pedido saiu para entrega.", "typingDelay": 3000, "clientRef": "pedido-1234-saiu" }Mídia
A apiwpp baixa o arquivo de media.url na hora do envio e o manda ao WhatsApp. A URL tem de ser https pública: sem credenciais na URL, sem endereços privados ou internos, em cada redirecionamento também (até 3). O arquivo pode ter até 50 MB e o download, até 30 segundos. Uma URL recusada ou fora do ar faz a tentativa falhar; esgotadas as tentativas, chega message.send_failed com reason: attempts_exhausted.
| Campo | Obrigatório | Descrição |
|---|---|---|
type | sim | image, video, audio, document ou sticker |
url | sim | URL https pública do arquivo |
caption | não | Legenda (imagem, vídeo e documento) |
fileName | não | Nome do arquivo que o contato vê (documento; padrão document) |
mimetype | só em document | Tipo do arquivo, como application/pdf; sem ele, a resposta é 400 |
ptt | não | Em audio, true envia como mensagem de voz |
gifPlayback | não | Em video, true reproduz como GIF |
{
"to": "5511988887777",
"media": {
"type": "document",
"url": "https://cdn.example.com/boletos/1234.pdf",
"mimetype": "application/pdf",
"fileName": "boleto-1234.pdf",
"caption": "Segue o seu boleto."
},
"clientRef": "boleto-1234"
}{ "to": "5511988887777", "media": { "type": "audio", "url": "https://cdn.example.com/audios/lembrete.ogg", "ptt": true } }Localização
latitude e longitude são obrigatórias (números); name e address são opcionais.
{ "to": "5511988887777", "location": { "latitude": -23.5614, "longitude": -46.6559, "name": "Loja Paulista", "address": "Av. Paulista, 1000" } }Template
Um template é um texto salvo na conexão, com variáveis no formato {{nome}} (letras, números e _, sem começar por número), e pode ter uma mídia. Crie uma vez com POST /connections/{id}/templates (escopo templates:write). O nome aceita letras, números, _ e -, é guardado em minúsculas e é único na conexão (409 se já existir):
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/templates \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "confirmacao_consulta", "body": "Olá {{nome}}, até amanhã às {{hora}}."}'Depois, envie pelo nome em template, com os valores em variables. As variáveis também valem na legenda da mídia do template, e a mídia do template substitui a da requisição:
{ "to": "5511988887777", "template": "confirmacao_consulta", "variables": { "nome": "Maria", "hora": "10h" }, "clientRef": "consulta-981" }Um template que não existe responde 404. Faltando alguma variável, a resposta é 400 com a lista:
{ "error": "Missing required variables", "missingVariables": ["hora"] }Verificar números e perfis
POST /connections/{id}/contacts/check pergunta ao WhatsApp se até 100 números estão registrados, com uma resposta por número, na mesma ordem. Com mais de 100, a resposta é 400.
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/contacts/check \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"phones": ["5511988887777", "5511955550000"]}'{
"results": [
{ "phone": "5511988887777", "exists": true, "jid": "[email protected]" },
{ "phone": "5511955550000", "exists": false }
]
}GET /connections/{id}/profile/{phone} traz o que o WhatsApp mostra do contato: status (o recado) e pictureUrl. Um campo escondido pelas configurações de privacidade dele não vem na resposta, e name hoje nunca é preenchido. As duas consultas exigem messages:send, porque perguntam ao WhatsApp a partir do número, como um envio, e a conexão precisa estar open.
Reações
POST /connections/{id}/react reage a uma mensagem pelo messageId dela (num message.incoming, o id está em data.raw.key.id); to é a conversa. Ao contrário do envio, a reação não pergunta ao WhatsApp em qual endereço um telefone está registrado: to é usado como veio, e só dígitos viram <dígitos>@s.whatsapp.net. Para uma conta registrada sem o nono dígito ou uma conversa com LID, isso reage no endereço errado e a resposta ainda é 200; por isso passe como to o data.jid do evento. Um emoji vazio remove a reação. Ao contrário do envio, a reação não passa pela fila: a resposta 200 com { "success": true } quer dizer que ela foi enviada.
{ "messageId": "3EB0C767D26A1D8A3F52", "to": "[email protected]", "emoji": "👍" }Editar e apagar mensagens enviadas, marcar mensagens como lidas e mostrar "digitando…" sem enviar são operações do plano PRO: veja Operações de mensagem.
A fila
Cada conexão tem a sua fila. Os envios saem um de cada vez, no ritmo do número: um intervalo de alguns segundos entre um envio e outro, um intervalo maior para o mesmo destinatário e os limites por minuto, hora e dia (mais baixos nos primeiros 14 dias do número). Uma tentativa que falha é repetida com espera crescente, até 3 tentativas no total.
GET /connections/{id}/queue(escopoconnections:read) mostra quantos envios aguardam (pending,scheduled), os limites atuais do número (limits), quanto deles já foi usado (usage) e o aquecimento (warmup).DELETE /connections/{id}/queue/{jobId}(escopomessages:send) cancela um envio que ainda não saiu e responde{ "cancelled": true }; um job que já saiu ou não existe responde404.
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/queue \
-H "Authorization: Bearer $API_KEY"{
"pending": 1,
"scheduled": 2,
"limits": { "perMinute": 3, "perHour": 60, "perDay": 200, "newRecipientsPerDay": 100 },
"usage": { "minute": 1, "hour": 12, "day": 40, "newRecipients": 7 },
"warmup": { "createdAt": 1789646400000, "messagesSent": 40, "isInWarmup": false, "endsAt": 1790856000000 }
}Quando o envio é recusado
Estas respostas vêm na hora, e nada entra na fila:
| Status | Quando | O que fazer |
|---|---|---|
400 | Corpo inválido, invalid_recipient, conexão fora de open, variáveis faltando (missingVariables) | Corrija a requisição ou espere a conexão abrir; repetir igual não resolve |
402 | code: subscription_inactive: o período de teste acabou ou uma fatura venceu e passou da carência | Regularize a assinatura no painel |
404 | Conexão ou template inexistente (ou de outra organização) | Confira os ids e o nome |
429 | Só num plano com limite de mensagens (o LITE e o PRO não têm): a cota da organização acabou (cabeçalho X-Usage-Percent) | Espere o próximo dia ou mês, ou mude de plano |
429 | error: new_recipient_cap_reached: o número já falou com o máximo de destinatários novos das últimas 24 horas | Espere os segundos de Retry-After |
503 | A instância que roda a conexão está mudando | Repita depois de Retry-After, com o mesmo clientRef |
Num plano com limite de mensagens, a cota conta junto as mensagens enviadas e as que estão na fila de todos os projetos da organização, e, perto do limite, a resposta de um envio aceito traz o cabeçalho X-Usage-Warning. Os detalhes de cada limite estão em Limites de envio, e os de cada erro, em Erros.
O que acontece depois
Cada envio é contado pelos webhooks do projeto:
| Evento | Quando |
|---|---|
message.outgoing | A mensagem saiu (origin: API, com o seu clientRef e o messageId do WhatsApp). Opcional: só para projetos com emitOutgoing: true, que também recebem o que é digitado no celular (origin: PHONE) |
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: attempts_exhausted, lease_expired, not_on_whatsapp ou reachout_timelocked (a conta está num bloqueio temporário de novas conversas) |
A resposta 202 não traz o messageId do WhatsApp: ele chega nesses eventos. Guarde o clientRef junto do seu registro para ligar um ao outro.
Próximos passos
- Webhooks e assinatura: receba os eventos acima e verifique a assinatura.
- Idempotência: repita envios sem duplicar mensagens.
- Limites de envio: o ritmo da fila, o aquecimento e os destinatários novos.
- Enviar mensagem: a referência completa, com exemplos em cURL, Node.js, PHP e Python.