Recaudo Docs

Conversations

WhatsApp templates

Check the approved templates available to send

List templates

GET /v1/whatsapp-templates

Returns all WhatsApp templates configured for your account. Includes the Meta approval status.

Request example
curl https://recaudo.app/api/v1/whatsapp-templates \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json"

Optional filters: status (approved, pending, rejected, paused…), category (UTILITY, MARKETING), language (es_MX, en_US…) and search. Each template includes the body text with its {{n}}, the positions (variables), header, footer and buttons; has_dynamic_suffix means the link is completed at send time with button_url_value.

Response
{
  "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}'} One template with the same detail.

Create a template and submit it to Meta

POST /v1/whatsapp-templates

Saves it in the WhatsApp Business account of the line (phone_number_id, optional; otherwise the default one) and submits it to Meta for approval in the same call. Returns 201 with status "pending"; the result arrives in the whatsapp_template.status_updated webhook and in the list.

Body
{
  "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" }
  ]
}

Rules checked before submitting

  • name: letters, numbers and underscore (lowercased). If it already exists in Recaudo or in Meta it returns 409 and leaves it untouched.
  • category: UTILITY or MARKETING. AUTHENTICATION templates are created from Recaudo.
  • body: up to 1024 characters; variables in sequence from {{1}} and never at the start or end. examples: one value per variable, in order.
  • header (optional): text (up to 60, no variables) or image, video or document with media_url (https; jpg/png, mp4 or pdf). footer: up to 60, no variables.
  • buttons (optional, up to 10): all quick_reply, or url (max 2) and phone_number (max 1). A link only accepts {{1}} at the end and then requires example.

WhatsApp lines

GET /v1/whatsapp-lines

The tenant WhatsApp lines, default first. The id is what phone_number_id accepts when sending a template and deploying a flow. status: active, inactive or restricted (Meta blocked it until restricted_until).

Send a template to a phone

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

Sends a Meta-approved template to any WhatsApp number, with or without a previous conversation. Use it for business-initiated notices: payment links, contract signing, reminders.

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: positional, as a list ["Ana", "..."] or an object {"1": "Ana"}. Identify the template with template_id or template_name.
  • phone_number_id (optional): sending line. If omitted, it goes out through the line of the template's WhatsApp account.
  • Status: subscribe your webhook to conversation.message.status_updated (delivered, read, failed) and conversation.message.received (replies and buttons).
  • 422 errors with error.code: template_not_found, invalid_phone_number, template_line_mismatch, no_sending_line, send_failed.
Was this page helpful? Thanks for letting us know.
Esc