Enviar mensajes de plantilla con variables personalizadas a través de WhatChimp API

Envía mensajes de plantilla con datos dinámicos de suscriptores a través del API

Updated 10 February 2026

Cuando envías mensajes de plantilla de WhatsApp a través de WhatChimp, a menudo quieres personalizarlos con información específica del suscriptor como nombres de empresa, ubicaciones, detalles de cuenta o preferencias. Los campos personalizados (también llamados variables personalizadas) te permiten almacenar estos datos directamente en el perfil de cada suscriptor. Cuando tu plantilla hace referencia a estos campos, el API automáticamente extrae los valores de los datos almacenados del suscriptor.

La diferencia clave con las variables de plantilla: no pasas los valores en cada solicitud de envío. En su lugar, configuras los datos en el suscriptor una vez, y el sistema los usa cada vez que envías una plantilla que necesita esos campos.

¿Necesitas enviar valores diferentes con cada mensaje? Si estás enviando datos dinámicos que cambian por mensaje (como códigos OTP, números de pedido o IDs de seguimiento), usa variables de plantilla en su lugar. Los campos personalizados son para datos que permanecen con el perfil del suscriptor.

Video: https://www.youtube.com/watch?v=yd1O0Sd_zDQ

Cómo funcionan las variables personalizadas con plantillas

Los campos personalizados se almacenan en el perfil del suscriptor en WhatChimp. Cuando envías una plantilla que incluye marcadores de posición de campos personalizados, el sistema automáticamente recupera los valores de los datos de ese suscriptor y los inserta en el mensaje.

Aquí está el flujo típico:

Paso A. Configuras company="Acme Corp" y country="United States" en un suscriptor usando el API o la interfaz.

Paso B. Tu mensaje de plantilla aprobado dice: "Hola {{first_name}}, oferta especial para clientes de {{company}} en {{country}}!"

Paso C. Llamas al API de envío solo con el nombre de plantilla y número de teléfono del suscriptor — sin parámetros de variables necesarios.

Paso D. El destinatario recibe: "Hola John, oferta especial para clientes de Acme Corp en United States!"

El sistema extrae "Acme Corp" y "United States" de los campos personalizados almacenados del suscriptor automáticamente. Nunca pasas estos valores en la solicitud de envío.

Paso 1: Crear campos personalizados

Antes de poder usar campos personalizados en plantillas o almacenarlos en suscriptores, necesitas crearlos en WhatChimp.

Paso A. Inicia sesión en tu cuenta de WhatChimp y navega a Subscriber Manager > Manage Custom Fields, o ve directamente a /whatsapp/subscriber/manager/custom-field/list.

Paso B. Haz clic en el botón Create para agregar un nuevo campo personalizado.

Paso C. Ingresa un nombre de campo (ej., company, country, customer_email, membership_level). Usa minúsculas con guiones bajos para consistencia.

Paso D. Selecciona el tipo de respuesta (texto, email, teléfono, número, etc.) según el tipo de datos que almacenará el campo.

Paso E. Haz clic en Save para crear el campo.

Repite este proceso para todos los campos personalizados que necesites. Los campos comunes incluyen nombre de empresa, ubicación, tipo de cuenta, industria o cualquier información específica del suscriptor que use tu negocio.

Paso 2: Configurar suscriptor y valores de campos personalizados a través del API

Antes de enviar una plantilla que usa campos personalizados, el suscriptor debe existir en tu cuenta de WhatChimp Y tener valores de campos personalizados asignados a su perfil.

Crear el suscriptor (si aún no existe)

Si el suscriptor aún no está en tu cuenta de WhatChimp, necesitas crearlo primero usando el API de crear suscriptor.

Endpoint: POST /api/v1/whatsapp/subscriber/create

Parámetros:

Solicitud de ejemplo:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/create \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phoneNumberID=1234567890" \
  -d "name=John Doe" \
  -d "phoneNumber=15551234567"

Respuesta exitosa:

{"status":"1","mesasge":"WhatsApp subscriber has been created."}

Si el suscriptor ya existe, el API devuelve "Something went wrong or subscriber already exist." — esto es esperado, y puedes saltarte este paso e ir directamente a asignar campos personalizados abajo.

Verificar campos personalizados disponibles

Recupera la lista de campos personalizados que has creado para verificar los nombres exactos de los campos.

Endpoint: POST /api/v1/whatsapp/subscriber/custom-fields/list

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/custom-fields/list \
  -d "apiToken=YOUR_API_TOKEN"

Respuesta:

{
  "status": "1",
  "message": "Custom fields retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "company",
      "reply_type": "text"
    },
    {
      "id": 2,
      "name": "country",
      "reply_type": "text"
    },
    {
      "id": 3,
      "name": "customer_email",
      "reply_type": "email"
    }
  ]
}

Toma nota de los nombres de campos que usarás en el siguiente paso.

Asignar campos personalizados al suscriptor

Ahora configura los valores de campos personalizados en el perfil del suscriptor. Esto funciona tanto si acabas de crear el suscriptor como si ya existía.

Endpoint: POST /api/v1/whatsapp/subscriber/chat/assign-custom-fields

Parámetros:

Solicitud de ejemplo:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/chat/assign-custom-fields \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d 'custom_fields={"company":"Acme Corp","country":"United States","customer_email":"john@acme.com"}'

Respuesta exitosa:

{
  "status": "1",
  "message": "Subscriber changes have been saved successfully."
}

Los valores de campos personalizados ahora están almacenados en el perfil de este suscriptor. Puedes actualizarlos en cualquier momento llamando nuevamente a este endpoint con nuevos valores.

También puedes configurar campos personalizados:

• Editando manualmente suscriptores en la interfaz de Subscriber Manager
• Importando contactos a través de CSV con columnas de campos personalizados
• Usando flujos de chatbot que capturan entrada del usuario y la guardan en campos personalizados
• Operaciones en masa a través del API de suscriptores

Paso 3: Crear una plantilla con campos personalizados

Ahora crea una plantilla de mensaje de WhatsApp que use tus campos personalizados.

Paso A. Navega a Bot Manager > Message Template en tu dashboard de WhatChimp.

Paso B. Haz clic en Create para comenzar una nueva plantilla.

Paso C. Escribe el cuerpo de tu mensaje. Cuando quieras insertar un campo personalizado, haz clic en el botón desplegable Custom Fields (con el ícono de engranaje) arriba del área de texto del cuerpo del mensaje. NO hagas clic en "Variables" — eso inserta variables de plantilla, que funcionan de manera diferente.

El desplegable Custom Fields muestra todos los campos personalizados que creaste en el Paso 1 (como Country, Email, FullName, etc.). Haz clic en cualquier nombre de campo para insertarlo en el cuerpo de tu mensaje de plantilla.

Ejemplo de cuerpo de plantilla:

Hola {{first_name}}, ¡tenemos una oferta especial para {{company}}!

Como cliente valioso en {{country}}, eres elegible para beneficios exclusivos. Haz clic abajo para saber más.

Paso D. Agrega cualquier botón, encabezado o pie de página que tu plantilla necesite.

Paso E. Haz clic en Save y envía para aprobación de Meta.

Espera a que Meta apruebe tu plantilla. Esto típicamente toma unas horas o un día. Una vez aprobada, puedes enviarla a través del API.

Paso 4: Enviar la plantilla a través del API

Ahora estás listo para enviar la plantilla. Nota que la solicitud de envío NO incluye parámetros de variables. Los valores de campos personalizados se extraen automáticamente de los datos almacenados del suscriptor.

Endpoint: GET/POST /api/v1/whatsapp/send

Parámetros:

Solicitud de ejemplo (GET):

https://app.whatchimp.com/api/v1/whatsapp/send?apiToken=YOUR_API_TOKEN&phone_number_id=1234567890&phone_number=15551234567&template_name=special_offer&language_code=en_US

Solicitud de ejemplo (POST):

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/send \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d "template_name=special_offer" \
  -d "language_code=en_US"

Respuesta exitosa:

{
  "status": "1",
  "message": "Message sent successfully",
  "data": {
    "message_id": "wamid.HBgNMTU1NTEyMzQ1NjcVAgARGBI5QTNDQTA3RjU4Q0M1MTBGMkEA"
  }
}

El sistema automáticamente extrae los valores de campos personalizados (company, country, customer_email) del perfil del suscriptor y los inserta en la plantilla. El destinatario ve un mensaje completamente personalizado sin que tengas que pasar esos valores en cada solicitud de envío.

Ejemplo de flujo de trabajo completo

Aquí está el proceso completo de extremo a extremo para enviar mensajes de plantilla con variables personalizadas:

Configuración única:

Paso A. Crea campos personalizados en la interfaz de WhatChimp (ej., company, country, membership_level).

Paso B. Crea y obtén aprobación para una plantilla que use esos campos personalizados.

Para cada suscriptor:

Paso C. Crea el suscriptor si aún no existe en WhatChimp:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/create \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phoneNumberID=1234567890" \
  -d "name=John Doe" \
  -d "phoneNumber=15551234567"

Salta este paso si el suscriptor ya existe en tu cuenta.

Paso D. Configura valores de campos personalizados en el suscriptor:

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/subscriber/chat/assign-custom-fields \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d 'custom_fields={"company":"Acme Corp","country":"United States","membership_level":"Gold"}'

Paso E. Envía la plantilla (sin parámetros de variables necesarios):

curl -X POST https://app.whatchimp.com/api/v1/whatsapp/send \
  -d "apiToken=YOUR_API_TOKEN" \
  -d "phone_number_id=1234567890" \
  -d "phone_number=15551234567" \
  -d "template_name=membership_update" \
  -d "language_code=en_US"

El suscriptor recibe un mensaje personalizado como: "Hola John, tu membresía Gold en Acme Corp está activa. Como cliente en United States, tienes acceso a beneficios exclusivos."

Solución de problemas

Artículos relacionados

• Template Variables vs Custom Variables
• Send Template Messages with Variables via WhatChimp API — Para datos dinámicos por mensaje como OTPs y números de pedido
• WhatChimp Subscriber Management API
• How to Manage Custom Fields and Labels
• Send Template Messages via WhatChimp API
• Getting Started with WhatChimp Developer API