Enviar mensaje con plantilla

POST /api/v1/message_templates/send

Este endpoint permite enviar un mensaje utilizando una plantilla predefinida de WhatsApp. Las plantillas permiten mantener un formato estandarizado y estructurado en la comunicación, asegurando que los mensajes enviados sean consistentes y cumplan con las políticas de WhatsApp Business API.

El mensaje se envía desde un número autorizado a un destinatario específico, permitiendo personalizar su contenido mediante la inclusión de parámetros dinámicos en el cuerpo del mensaje o en su encabezado. Esto es especialmente útil para enviar notificaciones automatizadas, recordatorios, confirmaciones de citas, entre otros casos de uso.

El endpoint requiere una solicitud POST con un cuerpo en formato JSON que especifique el número de origen, el destinatario, el nombre de la plantilla y los valores a reemplazar en los parámetros dinámicos. A continuación, se detalla su uso, incluyendo los parámetros requeridos, ejemplos de solicitud y la estructura de la respuesta.

ℹ Recuerda que:

La URL base para todas las solicitudes es: https://tu-dominio.c3.pe

Importante: reemplaza tu-dominio por el nombre de dominio específico que te haya proporcionado C3.

Solicitud

Cabeceras

Encabezado	Tipo	Obligatorio	Descripción
Authorization	String	✅ Sí	Token de autenticación (Bearer Token).
Content-Type	String	✅ Sí	Debe ser application/json.

Cuerpo de la solicitud

Atributo	Tipo	Obligatorio	Descripción
wa_number	String	✅ Sí	Número de WhatsApp desde el cual se enviará el mensaje.
destination	String	✅ Sí	Número de WhatsApp del destinatario.
template_name	String	✅ Sí	Nombre de la plantilla a utilizar.
header_param	Object/null	❌ No	Parámetro opcional que remplazará valor en el encabezado.
body_params	Array	❌ No	Lista de parámetros que reemplazarán valores en el cuerpo del mensaje.
body_params.key	String	✅ Sí	Clave del parámetro en la plantilla (ejemplo: "1").
body_params.value	String	✅ Sí	Valor que reemplazará la variable en la plantilla.
media_path	String	❌ No	Ruta interna del archivo devuelta por /api/v1/media-upload.
campaign_id	Integer	❌ No	ID de campaña de WhatsApp C3 para procesar las respuestas, si no se determina, las respuestas serán procesadas por el Chatbot.
sent_group	String	❌ No	Palabra clave que permite agrupar los envios, es útil para posteriores usos de filtrado, ej: Masivo navidad

Adjuntos Dinámicos

⚠️ Validaciones Estrictas del media_path

Si decides proveer un archivo mediante media_path, el sistema aplicará las siguientes validaciones:

1. Formatos: La extensión debe coincidir con el formato asignado a la plantilla en Meta:
   • Si la plantilla es DOCUMENT, sólo se acepta .pdf.
   • Si la plantilla es IMAGE, sólo se acepta .jpg, .jpeg, .png.
   • Si la plantilla es VIDEO, sólo se acepta .mp4.
   • Si la plantilla es de tipo TEXT o no admite cabeceras, la petición fallará.
2. Seguridad: El media_path provisto debe pertenecer exclusivamente a tu equipo (uploads/team<tu_id>/). El uso de archivos de otros equipos generará un error 403.

Comportamiento del Adjunto por Defecto: Si NO proporcionas el atributo media_path, el envío buscará y utilizará de forma automática el adjunto por defecto que hayas configurado previamente en la plataforma C3, asegurando la retrocompatibilidad con las plantillas ya existentes.

Ejemplo de solicitud completa

POST /api/v1/message_templates/send

El cuerpo de la solicitud debe enviarse en formato JSON e incluir los siguientes campos:

{
  "wa_number": "5117004531",
  "destination": "51947000255",
  "template_name": "recuperacion_de_atencion",
  "header_param": {"key": "1", "value": "Karla"},
  "body_params": [
    {
      "key": "1",
      "value": "el día de ayer"
    }
  ]
}

Ejemplo de solicitud con adjunto dinámico

El siguiente ejemplo muestra el uso de la propiedad media_path enviada previamente al servidor a través del endpoint /api/v1/media-upload.

{
  "wa_number": "5117484531",
  "destination": "51925177116",
  "template_name": "promos_del_mes",
  "media_path": "uploads/team1/mi_archivo_1711894400.pdf",
  "body_params": [
    {
      "key": "1",
      "value": "Juan Pérez"
    }
  ]
}

Respuesta

La API devuelve un json con la siguiente estructura.

Respuesta base 200

{
  "message": "La solicitud se completó con éxito!",
  "data": {
    "update_id": "msg_c3api_1748361117"
  }
}

Definición de atributos

Campo	Tipo	Descripción
message	String	Mensaje de respuesta del servidor.
data.update_id	String	Identificador único de la actualización.

Plantilla de ejemplo utilizada

{
  "name": "recuperacion_de_atencion",
  "status": "APPROVED",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Hola {{1}}"
    },
    {
      "type": "BODY",
      "text": "Disculpa si no pudimos responderte 😪 {{1}}. Estaremos más atentos para tu duda o pregunta."
    },
    {
      "type": "FOOTER",
      "text": "Gracias por tu comprensión."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Hablar con soporte",
          "payload": "soporte"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Programar una llamada",
          "payload": "programar_llamada"
        }
      ]
    }
  ],
  "id": "1242001217077846"
}

Errores generales

Código HTTP	Tipo	Causa común
401	Unauthorized	El token de acceso no fue proporcionado en el encabezado Authorization, es inválido o ha sido revocado. Verifique que el token sea correcto y esté activo.
422	Unprocessable Entity	La solicitud fue entendida, pero contiene errores semánticos que impiden su procesamiento. Esto puede deberse a: 1. Parámetros faltantes o inválidos (ej, from_date no es una fecha válida); 2. Recurso inexistente (wa_number no registrado en el sistema); 3. Violación de reglas de negocio (el rango de fechas excede el límite permitido).
500	Server Error	Error interno del servidor. Intenta nuevamente más tarde o contacta soporte técnico.