Pular para o conteúdo

Enviar mensagem

POST/connections/{id}/send

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.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador da conexão (o número) que envia.

Corpo da requisição

tostringobrigatório

Destinatá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.

messagestring

Texto da mensagem.

typingDelaynumber

Por quantos milissegundos o indicador “digitando…” aparece antes do envio. Padrão: 1500.

mediaobject

Mídia a partir de uma URL https pública.

media.typestringobrigatório

Tipo da mídia.

Valores: "image", "video", "audio", "document", "sticker"
media.urlstring · uriobrigatório

URL https pública do arquivo. Endereços privados e internos são recusados.

formato `^https://`
media.captionstring

Legenda.

media.fileNamestring

Nome do arquivo.

media.mimetypestring

Tipo MIME do arquivo (por exemplo, application/pdf). Obrigatório quando type é document.

media.pttboolean

Com audio, envia o áudio como mensagem de voz.

media.gifPlaybackboolean

Com video, reproduz o vídeo como GIF.

locationobject

Uma localização.

location.latitudenumberobrigatório

Latitude.

location.longitudenumberobrigatório

Longitude.

location.namestring

Nome do local.

location.addressstring

Endereço do local.

templatestring

Nome de um template da conexão (criado com POST /connections/{id}/templates). O texto e a mídia do template substituem message e media.

variablesobject

Valores das variáveis do template, por nome: {"nome": "Maria", "hora": "10h"}.

chaves livres, valores string
clientRefstring

Seu 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.

até 200 caracteres

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200Um 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.
202A 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
400invalid_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.
400A 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).
400O template precisa de variáveis que não vieram em variables: o corpo é {"error": "Missing required variables", "missingVariables": [...]}, com a lista das que faltam.
400FST_ERR_VALIDATIONO corpo não segue o schema da operação (por exemplo, sem to); message diz o que está errado.
401Sem chave de API, ou com uma chave inválida (desconhecida, revogada ou expirada).
402subscription_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.
403A chave de API não tem o escopo messages:send; a mensagem do erro cita o escopo que falta.
404A 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.
429new_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
429Só 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
429Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After.Cabeçalho: Retry-After
503A 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

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