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": "wb-123456789",
  "conversationId": "521234567890",
  "responderAgentId": "agent_123",
  "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

Canal y agente respondedor

El canal y el agente son independientes:

• channelId decide desde qué número/canal se envía.
• responderAgentId decide qué agente atenderá las respuestas.
• Si omites responderAgentId con un channelId canónico, la conversación nueva queda initiated y sin agente. El defaultAgentId del canal no se hereda (ese campo es solo para inbound).
• Si usas el identificador legacy (teléfono del agente), se conserva ese agente.
• Si no hay agente, el mensaje se envía igual. Cuando el contacto responde, el hilo pasa a supervised y sigue sin IA hasta que asignes un agente.
• Si ya existe una conversación activa para ese contacto y canal, conserva su agente actual.

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

Programación

Envía la plantilla inmediatamente, con un retraso o en una fecha específica. Después puedes consultarla, reprogramarla o cancelarla por messageId .

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": "2026-09-20T20:00:00Z"
}

Con delay (HTTP 202):

{
  "messageId": "msg_123xyz",
  "kind": "template",
  "status": "delayed",
  "timestamp": "2026-09-20T20:00:00Z",
  "executeAt": "2026-09-20T20:00:05.000Z",
  "delayMs": 5000
}

Con scheduleTime (HTTP 202):

{
  "messageId": "msg_123xyz",
  "kind": "template",
  "status": "scheduled",
  "timestamp": "2026-09-20T20:00:00Z",
  "executeAt": "2026-10-16T00:40:00.000Z",
  "scheduledTime": "2026-10-15T18:40:00"
}

Los envíos con delay o scheduleTime quedan aceptados, pero todavía no enviados. Consulta Mensajes Programados para conocer sus estados y reglas de ejecución.

Contacto bloqueado

Un contacto con status: \"blocked\" nunca recibe plantillas. La API responde:

{
  "code": 409,
  "error": "Conflict - The resource state conflicts with this request",
  "details": {
    "code": "CONTACT_BLOCKED",
    "clientId": "client_123",
    "status": "blocked"
  }
}

La comprobación también se repite al ejecutar mensajes diferidos o programados.

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