Enviar mensagem
Coloca a mensagem (texto, mídia, localização ou template) na fila do número e responde 202 com a posição na fila e o horário previsto. O envio acontece em seguida, no ritmo que protege o número, e os webhooks message.outgoing e message.delivery contam o que aconteceu com ele. Escopo necessário: messages:send.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador da conexão (o número) que envia.
Corpo da requisição
tostringobrigatórioDestinatário: um número de telefone com código do país e DDD (por exemplo, 5511988887777; só os dígitos são lidos) ou um JID: uma pessoa (…@s.whatsapp.net ou …@lid), um grupo (…@g.us), uma lista de transmissão ou um canal. Para um número, o gateway pergunta ao WhatsApp em qual endereço ele está registrado e envia para esse endereço.
messagestringTexto da mensagem.
typingDelaynumberPor quantos milissegundos o indicador “digitando…” aparece antes do envio. Padrão: 1500.
mediaobjectMídia a partir de uma URL https pública.
media.typestringobrigatórioTipo da mídia.
"image", "video", "audio", "document", "sticker"media.urlstring · uriobrigatórioURL https pública do arquivo. Endereços privados e internos são recusados.
media.captionstringLegenda.
media.fileNamestringNome do arquivo.
media.mimetypestringTipo MIME do arquivo (por exemplo, application/pdf). Obrigatório quando type é document.
media.pttbooleanCom audio, envia o áudio como mensagem de voz.
media.gifPlaybackbooleanCom video, reproduz o vídeo como GIF.
locationobjectUma localização.
location.latitudenumberobrigatórioLatitude.
location.longitudenumberobrigatórioLongitude.
location.namestringNome do local.
location.addressstringEndereço do local.
templatestringNome de um template da conexão (criado com POST /connections/{id}/templates). O texto e a mídia do template substituem message e media.
variablesobjectValores das variáveis do template, por nome: {"nome": "Maria", "hora": "10h"}.
clientRefstringSeu identificador do envio (o id do pedido, da notificação). É a chave de idempotência: um clientRef fica reservado por 7 dias na conexão, e a repetição responde 200 com o job original. Volta como clientRef nos eventos message.outgoing (origem API) e message.delivery da mensagem.
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | Um envio anterior com o mesmo clientRef, na mesma conexão, já enfileirou esta mensagem: a resposta traz o job original com "duplicate": true, e nada é enfileirado de novo. scheduledAt e position vêm null enquanto o envio original ainda está entrando na fila. |
| 202 | A mensagem entrou na fila. Traz jobId, scheduledAt (quando o envio está previsto, unix em milissegundos) e position (o lugar na fila). Num plano com limite de mensagens, perto desse limite a resposta traz o cabeçalho X-Usage-Warning (Approaching limit: …% used).Cabeçalho: X-Usage-Warning |
| 400 | invalid_recipientto não é um número de telefone nem o JID de uma pessoa, de um grupo, de uma lista de transmissão ou de um canal. O corpo traz error e message. |
| 400 | A conexão não está open (Connection not ready (status: …)), ou o corpo não traz message, media, location nem template, ou a mídia ou a localização estão incompletas (media.url; media.mimetype num document; location.latitude e location.longitude). |
| 400 | O template precisa de variáveis que não vieram em variables: o corpo é {"error": "Missing required variables", "missingVariables": [...]}, com a lista das que faltam. |
| 400 | FST_ERR_VALIDATIONO corpo não segue o schema da operação (por exemplo, sem to); message diz o que está errado. |
| 401 | Sem chave de API, ou com uma chave inválida (desconhecida, revogada ou expirada). |
| 402 | subscription_inactiveA organização dona da conexão não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Regularize o pagamento no painel e repita. |
| 403 | A chave de API não tem o escopo messages:send; a mensagem do erro cita o escopo que falta. |
| 404 | A conexão não existe ou não é de quem chama (o recurso de outra pessoa responde igual a um que não existe). Também quando o template não existe na conexão. |
| 429 | new_recipient_cap_reachedO número já alcançou o limite de destinatários novos das últimas 24 horas. O corpo traz error e message; espere os segundos de Retry-After.Cabeçalho: Retry-After |
| 429 | Só num plano com limite de mensagens (os planos LITE e PRO não têm): a cota diária ou mensal da organização acabou. O cabeçalho X-Usage-Percent traz o uso, e error diz qual limite foi; não há Retry-After, a cota volta no próximo dia ou mês.Cabeçalho: X-Usage-Percent |
| 429 | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After.Cabeçalho: Retry-After |
| 503 | A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere Retry-After segundos e tente de novo.Cabeçalho: Retry-After |
Detalhes
A conexão precisa estar open. O envio precisa de conteúdo: message, media, location ou template; só to é obrigatório no schema.
Envie um clientRef para tornar a requisição idempotente e correlacionar os eventos: repetir com o mesmo valor na mesma conexão responde 200 com o job original e "duplicate": true, sem enfileirar nada. A repetição é reconhecida antes das outras verificações do envio (template, status da conexão, cota), então não vira erro enquanto o job original existe. Veja Idempotência.
A resposta 202 traz o jobId da fila, não o id da mensagem no WhatsApp: o messageId chega nos eventos message.outgoing (com origin: "API") e message.delivery, com o seu clientRef. Se o envio aceito não acontecer (o número de to não está no WhatsApp, as tentativas acabaram, o número está com as novas conversas bloqueadas), um envio com clientRef gera o evento message.send_failed.
A cota do plano é da organização: as mensagens enviadas e enfileiradas de todos os projetos dela contam juntas. Um destinatário que não trocou mensagem com o número nos últimos 28 dias desde a conexão atual é um destinatário novo; parear de novo, mesmo o mesmo número, torna todos os contatos novos. O número tem um limite de destinatários novos a cada 24 horas, menor enquanto ele está conectado há menos de 14 dias (GET /connections/{id}/queue mostra o limite e o uso). Veja Limites de envio.
Guia: Enviar mensagens