Envio de mensagens — Prosalab Developers

escopo: messages:send

Envia uma mensagem de texto via WhatsApp (UAZAPI ou Meta Cloud).

Modelo de envio

Corpo da requisição

{
  "to": "5548999990000",
  "message": "Olá! Seu pedido foi confirmado.",
  "connection_id": "<opcional — UUID da conexão>"
}

Resposta (200)

Corpo da resposta

{
  "success": true,
  "data": {
    "wamid": "<id-da-meta-ou-provider>",
    "provider": "uazapi",
    "message_id": "<uuid>",
    "contact_id": "<uuid>"
  }
}

Erros

Status	Código	Quando ocorre
400	MISSING_FIELD	Campo obrigatório ausente no corpo (to, message)
400	INVALID_PHONE	Número de telefone não pôde ser normalizado
403	CONTACT_OPTED_OUT	Contato pediu para não receber mensagens (opted_out_at)
403	CONTACT_BLOCKED	Contato bloqueado
403	EXTERNAL_AI_DISABLED	IA externa desligada para o contato (o operador assumiu o atendimento). Só volta quando alguém religar pelo menu de IA no inbox; templates por /api/v1/send/template não são afetados
404	NOT_FOUND	connection_id enviado não pertence à empresa
502	PROVIDER_ERROR	Falha no envio pelo provedor (UAZAPI/Meta)
503	CONTACT_STATE_UNAVAILABLE	Não foi possível ler o estado do contato (indisponibilidade transitória) — re-tente após Retry-After; não é um estado do contato

Exemplo

curl

curl -s -X POST -H "Authorization: Bearer <sua-key>" -H "Content-Type: application/json" \
  -d '{"to":"5548999990000","message":"Olá! Seu pedido foi confirmado.","connection_id":"<opcional — UUID da conexão>"}' \
  https://www.prosalab.com/api/v1/send/message

POST/api/v1/send/template

escopo: messages:send

Envia uma mensagem de template/HSM aprovado na Meta Cloud. Template com variável (corpo, cabeçalho ou botão de URL) exige o array components — sem ele a Meta recebe o template sem preenchimento.

components é repassado à Meta EXATAMENTE como enviado — esta rota não monta, valida nem completa nenhum componente. Template com variável enviado sem components chega à Meta sem preenchimento; a falha é da Meta, não desta rota.
Botão de URL dinâmica: a Meta aceita UMA variável por botão, e apenas no FIM de uma URL já aprovada — o valor enviado em parameters[0].text é concatenado à base aprovada. index é a posição do botão no template ("0" para o primeiro), enviado como STRING. URL fora da base aprovada faz a Meta rejeitar o envio inteiro.
Não há endpoint para listar templates aprovados, e template_name/language_code NÃO são validados contra o catálogo antes do envio. Nome inexistente, idioma errado ou template não aprovado só falham na Meta e voltam como 502 PROVIDER_ERROR genérico — confira o nome e o idioma no Gerenciador da Meta antes de disparar.
Exige conexão WhatsApp Meta Cloud. Informando connection_id, ele PRECISA ser Meta Cloud; sem ele, a conexão Meta Cloud conectada da empresa é resolvida automaticamente. Conexão de outro tipo também volta como 502, não 400.
A mensagem é gravada com o template_name usado no disparo, o que permite auditar e deduplicar envios por template.

Modelo de envio

Corpo da requisição

{
  "to": "5548999990000",
  "template_name": "renovacao_proposta",
  "language_code": "pt_BR",
  "connection_id": "<opcional — UUID da conexão>",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Maria"
        }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": "0",
      "parameters": [
        {
          "type": "text",
          "text": "aB3xK9"
        }
      ]
    }
  ]
}

Resposta (200)

Corpo da resposta

{
  "success": true,
  "data": {
    "wamid": "<id-da-meta>",
    "provider": "meta_cloud",
    "message_id": "<uuid>",
    "contact_id": "<uuid>"
  }
}

Erros

Status	Código	Quando ocorre
400	MISSING_FIELD	Campo obrigatório ausente (to, template_name, language_code)
400	INVALID_PHONE	Número de telefone não pôde ser normalizado
403	CONTACT_OPTED_OUT	Contato pediu para não receber mensagens (opted_out_at)
403	CONTACT_BLOCKED	Contato bloqueado
404	NOT_FOUND	connection_id enviado não pertence à empresa
409	DUPLICATE_SEND	Mesmo template ao mesmo contato dentro da janela (MARKETING: 24h por nome; UTILITY/AUTH: conteúdo idêntico em 10 min) — data traz message_id, sent_at e next_eligible_at; NÃO re-tente antes de next_eligible_at. data ausente quando a recusa vem de dois POSTs simultâneos (envio anterior ainda em voo)
502	PROVIDER_ERROR	Falha no envio pela Meta — template/idioma não aprovado, components inválido, URL fora da base aprovada ou conexão que não é Meta Cloud
503	CONTACT_STATE_UNAVAILABLE	Não foi possível ler o estado do contato (indisponibilidade transitória) — re-tente após Retry-After; não é um estado do contato

Exemplo

curl

curl -s -X POST -H "Authorization: Bearer <sua-key>" -H "Content-Type: application/json" \
  -d '{"to":"5548999990000","template_name":"renovacao_proposta","language_code":"pt_BR","connection_id":"<opcional — UUID da conexão>","components":[{"type":"body","parameters":[{"type":"text","text":"Maria"}]},{"type":"button","sub_type":"url","index":"0","parameters":[{"type":"text","text":"aB3xK9"}]}]}' \
  https://www.prosalab.com/api/v1/send/template