Recaudo Docs

Conversas

Modelos de WhatsApp

Consulte os modelos aprovados disponíveis para envio

Listar modelos

GET /v1/whatsapp-templates

Retorna todos os modelos de WhatsApp configurados na sua conta. Inclui o status de aprovação da Meta.

Exemplo de requisição
curl https://recaudo.app/api/v1/whatsapp-templates \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json"

Filtros opcionais: status (approved, pending, rejected, paused…), category (UTILITY, MARKETING), language (es_MX, en_US…) e search. Cada modelo traz o texto do corpo (body) com seus {{n}}, as posições (variables), o cabeçalho, o rodapé e os botões; has_dynamic_suffix indica que o link é completado no envio com button_url_value.

Resposta
{
  "object": "list",
  "data": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Documento listo",
      "meta_template_name": "documento_listo",
      "status": "approved",
      "category": "UTILITY",
      "language": "es_MX",
      "body": "Hola {{1}}, tu documento {{2}} por {{3}} está listo.",
      "variables": [1, 2, 3],
      "variable_count": 3,
      "header": { "type": "text", "text": "Tu documento", "variables": [], "media_url": null },
      "footer": "Gracias por tu compra",
      "buttons": [
        { "type": "URL", "text": "Descargar", "url": "https://example.com/d/{{1}}", "has_dynamic_suffix": true, "phone": null }
      ]
    }
  ]
}
GET /v1/whatsapp-templates/{'{id}'} Um modelo com o mesmo detalhe.

Criar um modelo e enviá-lo à Meta

POST /v1/whatsapp-templates

Salva-o na conta do WhatsApp Business da linha (phone_number_id, opcional; senão, a padrão) e o envia para aprovação da Meta na mesma chamada. Responde 201 com status "pending"; o resultado chega no webhook whatsapp_template.status_updated e na lista.

Corpo
{
  "name": "documento_listo",
  "language": "es_MX",
  "category": "UTILITY",
  "body": "Hola {{1}}, tu documento {{2}} ya está disponible.",
  "examples": ["Ana", "F-120"],
  "footer": "Gracias por tu compra",
  "buttons": [
    { "type": "url", "text": "Descargar", "url": "https://example.com/d/{{1}}", "example": "abc123" }
  ]
}

Regras validadas antes de enviar

  • name: letras, números e sublinhado (convertido para minúsculas). Se já existir no Recaudo ou na Meta, responde 409 e não mexe nele.
  • category: UTILITY ou MARKETING. Os de AUTHENTICATION são criados no Recaudo.
  • body: até 1024 caracteres; variáveis em sequência desde {{1}} e nunca no início nem no fim. examples: um valor por variável, em ordem.
  • header (opcional): text (até 60, sem variáveis) ou image, video ou document com media_url (https; jpg/png, mp4 ou pdf). footer: até 60, sem variáveis.
  • buttons (opcional, até 10): todos quick_reply, ou url (máx. 2) e phone_number (máx. 1). Um link só aceita {{1}} no final e então exige example.

Linhas de WhatsApp

GET /v1/whatsapp-lines

As linhas de WhatsApp do tenant, a padrão primeiro. O id é o que phone_number_id aceita ao enviar um modelo e ao implantar um fluxo. status: active, inactive ou restricted (a Meta a bloqueou até restricted_until).

Enviar modelo para um telefone

POST /v1/conversations/send-template-to-phone

Envia um modelo aprovado pela Meta para qualquer número de WhatsApp, com ou sem conversa anterior. Use para avisos iniciados pela empresa: links de pagamento, assinatura de contrato, lembretes.

curl -X POST https://recaudo.app/api/v1/conversations/send-template-to-phone \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5215511112222",
    "template_name": "payment_link_message2",
    "variables": ["Ana López", "https://recaudo.app/pay/abc123", "Plan Previsión", "$1,983.45"],
    "phone_number_id": "opcional: UUID o meta_phone_number_id de la línea"
  }'
{
  "object": "conversation_message",
  "data": { "id": "9b1f…", "status": "sent", "external_id": "wamid.HBgN…" },
  "conversation_id": "01a1…",
  "from": { "phone_number_id": "fa8a…", "phone_number": "+5212202110494" }
}
  • variables: posicionais, como lista ["Ana", "..."] ou objeto {"1": "Ana"}. Indique o modelo com template_id ou template_name.
  • phone_number_id (opcional): linha de envio. Se omitido, sai pela linha da conta de WhatsApp do modelo.
  • Status: assine no seu webhook conversation.message.status_updated (entregue, lido, falhou) e conversation.message.received (respostas e botões).
  • Erros 422 com error.code: template_not_found, invalid_phone_number, template_line_mismatch, no_sending_line, send_failed.
Esta página ajudou? Obrigado por avisar.
Esc