Saltar al contenido
ComdigDocs

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

Solicitud#

POSThttps://api.comdig.co/v1/api-send-template

Permiso requerido: templates:send

Parámetros del cuerpo#

Parámetros del cuerpo
NombreTipoRequeridoDescripción
phonestringSi no hay wa_user_idTeléfono del destinatario en formato E.164.
wa_user_idstringNoID de usuario de WhatsApp, en lugar de phone.
template_namestringSíNombre de una plantilla aprobada.
variablesarray<string>NoVariables del cuerpo ({{1}}, {{2}}…) en orden.
header_variablesarray<string>NoVariables del encabezado de texto.
header_mediaobjectNoArchivo del encabezado.
header_media.typestringSíTipo de archivo.Valores: image | video | document
header_media.urlstringSíURL pública del archivo.
header_media.filenamestringNoNombre del archivo (útil para documentos).
header_image_urlstringNoHeredado. Equivale a header_media con type image.Heredado
buttonsarray<object>NoParámetros de los botones de la plantilla.
buttons[].sub_typestringSíTipo de botón.Valores: url | copy_code | quick_reply
buttons[].indexintegerSíPosición del botón en la plantilla.
buttons[].parameterstringSíValor dinámico del botón.
contact_namestringNoNombre del contacto.
phone_number_idstringNoLínea de envío (si hay varias activas).
inbox_idstringNoAlternativa a phone_number_id.
badge_labelstringNoTexto de la insignia.Por defecto: APIMáx. 40 caracteres
badge_colorstringNoColor de la insignia.Valores: cyan | blue | purple | pink | slate | tealPor defecto: cyan
source_labelstringNoEtiqueta del origen del envío.Máx. 40 caracteres

Ejemplo#

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"
  }
}'

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#

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)#

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#

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#

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#

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#

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#

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"
}'