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.

Las respuestas que los clientes envíen pueden ser dirigidas o procesadas de diferentes formas, como una campaña o un chatbot específico, según la configuración del parámetro response_handler.

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`.
response_handler	String	❌ No	`CAMPAIGN` o `CHATBOT`. Define a dónde se deriva la respuesta del cliente. Por defecto: `CAMPAIGN`.
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.
bot_id	Integer	❌ No	ID del bot que debe atender la respuesta. Requerido si `response_handler = 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:

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á.
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

http

POST /api/v1/message_templates/send

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

json

{
  "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 manejo de respuesta

El siguiente ejemplo muestra cómo configurar el manejo de las respuestas del cliente mediante el parámetro response_handler.

Para derivar respuestas a un chatbot:

json

{
  "wa_number": "5117484531",
  "destination": "51925177116",
  "template_name": "promos_del_mes",
  "response_handler": "CHATBOT",
  "bot_id": 123,
  "body_params": [
    {
      "key": "1",
      "value": "Juan Pérez"
    }
  ]
}

Para derivar respuestas a una campaña:

json

{
  "wa_number": "5117484531",
  "destination": "51925177116",
  "template_name": "promos_del_mes",
  "response_handler": "CAMPAIGN",
  "campaign_id": 456,
  "body_params": [
    {
      "key": "1",
      "value": "Juan Pérez"
    }
  ]
}

Validaciones

En caso de error de validación, tendrás los siguientes:

response_handler con un valor distinto de CAMPAIGN/CHATBOT → "El atributo response_handler debe ser CAMPAIGN o CHATBOT".
response_handler = "CHATBOT" sin bot_id → "El atributo bot_id es requerido cuando response_handler es CHATBOT".
bot_id que no existe → "El bot con el ID: {bot_id} no existe!".

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.

json

{
  "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`

json

{
  "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

json

{
  "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.

Enviar mensaje con plantilla ​

Solicitud ​

Cabeceras ​

Cuerpo de la solicitud ​

Adjuntos Dinámicos ​

Ejemplo de solicitud completa ​

Ejemplo de solicitud con manejo de respuesta ​

Ejemplo de solicitud con adjunto dinámico ​

Respuesta ​

Respuesta base 200 ​

Definición de atributos ​

Plantilla de ejemplo utilizada ​

Errores generales ​

Enviar mensaje con plantilla

Solicitud

Cabeceras

Cuerpo de la solicitud

Adjuntos Dinámicos

Ejemplo de solicitud completa

Ejemplo de solicitud con manejo de respuesta

Ejemplo de solicitud con adjunto dinámico

Respuesta

Respuesta base `200`

Definición de atributos

Plantilla de ejemplo utilizada

Errores generales