Enviar (ou agendar) uma mensagem

POST 
/messages

Único caminho de envio. O que muda entre um texto e um template é o type no corpo — não a URL.

type	Para quê
text	Texto livre. Só dentro da janela de 24 h
template	Template aprovado. Abre conversa a qualquer momento
test	Igual a template, com o hello_world como padrão e erros traduzidos

Precisa de imagem, vídeo, documento, botões ou carrossel? O caminho é o espelho: POST /v1/{phone_number_id}/messages aceita o payload da Cloud API inteiro, com qualquer tipo que a Meta suporte.

Agendamento. Com sendAt (instante ISO 8601) ou delaySeconds (relativo), a resposta é 202 e a mensagem entra na fila. Direito de uso e número são reconferidos na hora de enviar, não agora.

Idempotência. Com o header Idempotency-Key, uma repetição da mesma chamada devolve a primeira resposta, com Idempotent-Replayed: true, e nada é enviado de novo — nem quando a primeira resposta foi um erro. A mesma chave com outro corpo é recusada com 422 idempotency_key_reused; enquanto a primeira requisição ainda roda, a repetição recebe 409 idempotency_in_progress.

Request

Responses

201

Registro encontrado.

202

Aceita para envio posterior.

401

Token ausente, malformado, desconhecido ou revogado (authentication), ou conta suspensa (tenant_inactive).

402

Sem direito de uso (payment_required). O corpo traz o motivo em reason e a saída em action: o que fazer (kind) e a página do painel onde se faz (url).

403

O recurso informado não pertence à sua conta (forbidden), ou o caminho está na lista de bloqueio do espelho (forbidden_endpoint), ou a sua API key é restrita a alguns números e a operação é da conta inteira (forbidden).

409

Conflito com o estado atual da conta.

422

Payload reprovado na validação (invalid_request, com o detalhamento em issues) ou recusado pela Meta (meta_error, com o corpo original em meta).

429

Limite de requisições excedido (rate_limit).

Response Headers

Retry-After

Segundos a aguardar antes de tentar de novo.

X-RateLimit-Category

Categoria do limite aplicada — send, media ou default.

X-RateLimit-Scope

Qual balde os outros headers descrevem — key (a API key), session (o painel) ou account (o teto da conta).

X-RateLimit-Limit

Teto de requisições da categoria na janela atual.

X-RateLimit-Remaining

Requisições restantes na janela atual.