Pular para o conteúdo

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.

Ver em Markdown

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"}'
202
{ "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:

FormatoDestinatário
[email protected]Uma pessoa, pelo telefone
…@lidUma pessoa identificada só pelo LID (o jid de um evento, veja LID e contact.resolved)
…@g.usUm grupo em que o número está (veja Listar grupos)
…@broadcast, …@newsletterUma 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

jsonTexto com 3 s de digitando…
{ "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.

CampoObrigatórioDescrição
typesimimage, video, audio, document ou sticker
urlsimURL https pública do arquivo
captionnãoLegenda (imagem, vídeo e documento)
fileNamenãoNome do arquivo que o contato vê (documento; padrão document)
mimetypesó em documentTipo do arquivo, como application/pdf; sem ele, a resposta é 400
pttnãoEm audio, true envia como mensagem de voz
gifPlaybacknãoEm video, true reproduz como GIF
jsonDocumento
{
  "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"
}
jsonMensagem de voz
{ "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.

jsonLocalização
{ "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):

bashVer na referência
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:

jsonEnviar o template
{ "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:

400
{ "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.

bashVer na referência
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"]}'
200
{
  "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.

jsonReagir
{ "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 (escopo connections: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} (escopo messages:send) cancela um envio que ainda não saiu e responde { "cancelled": true }; um job que já saiu ou não existe responde 404.
bashVer na referência
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/queue \
  -H "Authorization: Bearer $API_KEY"
200
{
  "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:

StatusQuandoO que fazer
400Corpo 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
402code: subscription_inactive: o período de teste acabou ou uma fatura venceu e passou da carênciaRegularize a assinatura no painel
404Conexão ou template inexistente (ou de outra organização)Confira os ids e o nome
429Só 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
429error: new_recipient_cap_reached: o número já falou com o máximo de destinatários novos das últimas 24 horasEspere os segundos de Retry-After
503A instância que roda a conexão está mudandoRepita 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:

EventoQuando
message.outgoingA 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.deliveryO status mudou: sent, delivered, read ou failed, com o messageId e o clientRef
message.send_failedUm 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

Esta página ajudou? · Atualizado em 29 set 2026