Enviar plantilla de mensaje

Envía una plantilla de WhatsApp aprobada para iniciar una conversación con un cliente. Si ya existe una conversación abierta, el mensaje se añade a ella; si no, se crea una nueva.

POST https://api.platica.mx/v1/messages/template

Cuerpo de la solicitud

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "campaignId": "pV6PvG2lc8ChQb2VmETr",
  "template": {
    "name": "bienvenida_cliente",
    "params": ["Juan", "Premium"],
    "type": "image",
    "file": "https://cdn.assets.com/welcome_image.jpg",
    "buttons": [
      {
        "index": 0,
        "parameters": [{ "type": "text", "text": "promo/enero" }]
      }
    ]
  },
  "client": {
    "name": "José",
    "customFields": {
      "placas": "ABC123",
      "id_recepcion": "REC001"
    }
  }
}

Parámetros del cuerpo

"buttons": [
  {
    "index": 0,
    "parameters": [{ "type": "text", "text": "promo/enero" }]
  },
  {
    "index": 1,
    "sub_type": "otp",
    "parameters": [{ "type": "text", "text": "482910" }]
  }
]

Validación contra la plantilla

Al recibir la solicitud, el API verifica que el payload sea compatible con la definición de la plantilla registrada en WhatsApp. Si hay incompatibilidades, se devuelve un error 400 con el detalle de cada problema.

Las reglas que se validan automáticamente son:

• Cantidad de params: debe coincidir exactamente con el número de variables {{1}}, {{2}}... en el cuerpo de la plantilla
• Encabezado multimedia: si la plantilla tiene encabezado de imagen, video o documento, template.type y template.file son obligatorios y type debe coincidir con el formato definido
• Índices de botones: cada index en template.buttons debe corresponder a un botón existente en la plantilla
• Variables de botones URL: el valor de text debe ser un segmento de ruta, no una URL completa

{
  "message": "Template payload is incompatible with template configuration",
  "template": "bienvenida_cliente",
  "errors": [
    {
      "field": "template.params",
      "message": "The number of params does not match the template definition",
      "expected": 2,
      "received": 1
    },
    {
      "field": "template.type",
      "message": "This template requires media header type",
      "expected": "image",
      "received": null,
      "example": {
        "type": "image",
        "file": "https://example.com/your-media-file"
      }
    }
  ]
}

Respuesta

La respuesta varía según si el mensaje se envía de forma inmediata, diferida o programada.

Envío inmediato:

{
  "messageId": "msg_123xyz",
  "status": "sent",
  "timestamp": "2025-02-14T12:00:00Z"
}

Con delay:

{
  "messageId": "msg_123xyz",
  "status": "delayed",
  "timestamp": "2025-02-14T12:00:00Z",
  "executeAt": "2025-02-14T12:00:05.000Z",
  "delayMs": 5000
}

Con scheduleTime:

{
  "messageId": "msg_123xyz",
  "status": "scheduled",
  "timestamp": "2025-02-14T12:00:00Z",
  "executeAt": "2025-07-01T00:40:00.000Z",
  "scheduledTime": "2025-07-01T18:40:00"
}

Reglas de WhatsApp

Plantillas obligatorias

Para iniciar una conversación debes usar una plantilla pre-aprobada. No puedes enviar mensajes de texto libre hasta que el cliente responda.

Ventana de 24 horas

Las conversaciones permanecen activas durante 24 horas desde el último mensaje del cliente.

Si el cliente NO responde:

• Envías la plantilla
• El cliente no responde
• No puedes enviar más mensajes hasta que responda

Si el cliente SÍ responde:

• Envías la plantilla
• El cliente responde
• Puedes enviar mensajes libremente durante 24 horas
• La ventana se reinicia con cada mensaje del cliente

Limitaciones de entrega

WhatsApp puede bloquear mensajes por:

• Restricciones del país del cliente
• Números en experimentos de WhatsApp
• Clientes que desactivaron notificaciones de marketing

Consultar estado

Verifica si tu mensaje fue entregado:

1. Desde la bandeja de entrada de la plataforma
2. Usando el endpoint Obtener Conversación