Referencia de la API
Enviar plantilla
Envía una plantilla de WhatsApp aprobada, con variables, encabezado multimedia y botones dinámicos.
POST/api-send-template
En esta página
Solicitud#
POSThttps://api.comdig.co/v1/api-send-template
Permiso requerido: templates:send
Parámetros del cuerpo#
| Nombre | Tipo | Requerido | Descripción |
|---|---|---|---|
phone | string | Si no hay wa_user_id | Teléfono del destinatario en formato E.164. |
wa_user_id | string | No | ID de usuario de WhatsApp, en lugar de phone. |
template_name | string | Sí | Nombre de una plantilla aprobada. |
variables | array<string> | No | Variables del cuerpo ({{1}}, {{2}}…) en orden. |
header_variables | array<string> | No | Variables del encabezado de texto. |
header_media | object | No | Archivo del encabezado. |
header_media.type | string | Sí | Tipo de archivo.Valores: image | video | document |
header_media.url | string | Sí | URL pública del archivo. |
header_media.filename | string | No | Nombre del archivo (útil para documentos). |
header_image_url | string | No | Heredado. Equivale a header_media con type image.Heredado |
buttons | array<object> | No | Parámetros de los botones de la plantilla. |
buttons[].sub_type | string | Sí | Tipo de botón.Valores: url | copy_code | quick_reply |
buttons[].index | integer | Sí | Posición del botón en la plantilla. |
buttons[].parameter | string | Sí | Valor dinámico del botón. |
contact_name | string | No | Nombre del contacto. |
phone_number_id | string | No | Línea de envío (si hay varias activas). |
inbox_id | string | No | Alternativa a phone_number_id. |
badge_label | string | No | Texto de la insignia.Por defecto: APIMáx. 40 caracteres |
badge_color | string | No | Color de la insignia.Valores: cyan | blue | purple | pink | slate | tealPor defecto: cyan |
source_label | string | No | Etiqueta del origen del envío.Máx. 40 caracteres |
Ejemplo#
curl -X POST "https://api.comdig.co/v1/api-send-template" \
-H "X-API-Key: $COMDIG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+573001234567",
"template_name": "promo_noviembre",
"variables": [
"Ana"
],
"header_media": {
"type": "image",
"url": "https://ejemplo.com/promo.jpg"
}
}'Respuestas#
200Plantilla enviada.
JSON
{
"success": true,
"message_id": "wamid.HBgMNTczMDAxMjM0NTY3FQIAERgS",
"conversation_id": "8f1c2a4e-3b7d-4e9a-9c11-2d5f6a7b8c90",
"contact_id": "1d2e3f4a-5b6c-7d8e-9f01-a2b3c4d5e6f7",
"rendered_text": "Hola Ana, tu pago de $120.000 fue recibido."
}404Plantilla no encontrada.
JSON
{
"error": "Descripción del error"
}502Error de Meta. Puede incluir details, meta_code y delivery_stage (before_meta, meta_error o meta_unknown), que indica si Meta pudo haber recibido el mensaje.
JSON
{
"error": "Descripción del error",
"delivery_stage": "meta_error"
}Ejemplos de uso#
Plantilla con imagen#
curl -X POST "https://api.comdig.co/v1/api-send-template" \
-H "X-API-Key: $COMDIG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+573001234567",
"template_name": "promo_noviembre",
"variables": [
"Ana"
],
"header_media": {
"type": "image",
"url": "https://ejemplo.com/promo.jpg"
}
}'Botón URL dinámico (carrito abandonado)#
curl -X POST "https://api.comdig.co/v1/api-send-template" \
-H "X-API-Key: $COMDIG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+573001234567",
"template_name": "carrito_abandonado",
"variables": [
"Ana",
"3"
],
"buttons": [
{
"sub_type": "url",
"index": 0,
"parameter": "carrito/8842"
}
]
}'Cupón con copy_code#
curl -X POST "https://api.comdig.co/v1/api-send-template" \
-H "X-API-Key: $COMDIG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+573001234567",
"template_name": "cupon_descuento",
"variables": [
"Ana",
"15%"
],
"buttons": [
{
"sub_type": "copy_code",
"index": 0,
"parameter": "ANA15"
}
]
}'Encabezado de video#
curl -X POST "https://api.comdig.co/v1/api-send-template" \
-H "X-API-Key: $COMDIG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+573001234567",
"template_name": "lanzamiento_producto",
"header_media": {
"type": "video",
"url": "https://ejemplo.com/lanzamiento.mp4"
}
}'Encabezado de documento PDF#
curl -X POST "https://api.comdig.co/v1/api-send-template" \
-H "X-API-Key: $COMDIG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+573001234567",
"template_name": "factura_emitida",
"variables": [
"FAC-1029"
],
"header_media": {
"type": "document",
"url": "https://ejemplo.com/FAC-1029.pdf",
"filename": "FAC-1029.pdf"
}
}'Encabezado de texto con variable#
curl -X POST "https://api.comdig.co/v1/api-send-template" \
-H "X-API-Key: $COMDIG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+573001234567",
"template_name": "recordatorio_cita",
"header_variables": [
"Ana"
],
"variables": [
"martes 24",
"10:00 a. m."
]
}'Insignia personalizada#
curl -X POST "https://api.comdig.co/v1/api-send-template" \
-H "X-API-Key: $COMDIG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+573001234567",
"template_name": "pago_recibido",
"variables": [
"Ana",
"$120.000"
],
"badge_label": "Facturación",
"badge_color": "teal",
"source_label": "Sistema de cobro"
}'