Cómo disparar Mensaje Activo vía API por el canal SMS – Blip | Blip Help

Objetivo

Este artículo muestra cómo usar la API de Campañas (Active Campaign) para crear, configurar y disparar una campaña de mensaje activo por el canal SMS. Cubre el flujo paso a paso (/campaigns, /audiences, /messages, /dispatch) y los flujos combinados (/campaign/full y /campaign/full/v2), que hacen todo en una sola llamada.

Prerequisitos

El canal SMS debe estar habilitado para tu cuenta/entorno. Si no está habilitado, cualquier solicitud con channelType = SMS será rechazada con error de validación.
Las solicitudes se envían como comandos del protocolo LIME (Set/Get), autenticados con la identidad del bot.

Visión general del flujo

Existen dos maneras de disparar una campaña SMS:

Flujo paso a paso — cuatro llamadas separadas: crear campaña, registrar audiencia, definir el mensaje y disparar. Da más control sobre cada etapa antes del envío.
Flujo combinado — una sola llamada que crea la campaña, registra la audiencia, define el mensaje y dispara. Usa /campaign/full para la mayoría de los casos, o /campaign/full/v2 para bases grandes (vía archivo) o filtro de usuarios.

Crear la campaña — SET /campaigns

Crea el registro de la campaña, definiendo el canal como SMS.

Tipo de contenido (mime type): application/vnd.iris.activecampaign.campaign+json

Ejemplo de solicitud

{
  "id": "campaign-sms-001",
  "name": "Campaña SMS - Recordatorio de pago",
  "campaignType": "INDIVIDUAL",
  "channelType": "SMS"
}

Campos

Campo	Obligatorio	Descripción
id	Sí	Identificador único de la campaña, definido por ti.
name	Sí	Nombre descriptivo de la campaña.
campaignType	Sí	INDIVIDUAL (un destinatario), BATCH (varios destinatarios).
channelType	Sí	Usa SMS.
fileUrl	No	URL de un archivo CSV con la lista de destinatarios, usado cuando campaignType = BATCH.
scheduled	No	Fecha/hora para programar el envío. Si se omite, la campaña se trata como inmediata.
notificationEmail / notificationEmailLanguage	No	Correo electrónico (e idioma) para recibir notificación en caso de que la campaña falle.
tags	No	Lista de etiquetas para agrupar y filtrar campañas en reportes.

Si el canal SMS no está habilitado en tu entorno, esta llamada devuelve error de validación y la campaña no se crea.

Registrar la audiencia — SET /audiences/{campaignId}

Agrega los destinatarios que recibirán el mensaje SMS.

Tipo de contenido: application/vnd.iris.activecampaign.audience+json

Ejemplo de solicitud (lista de destinatarios)

[
  {
    "recipient": "+5511999990000",
    "recipientType": "PHONENUMBER",
    "channelType": "SMS",
    "messageParams": {
      "nombre": "Maria",
      "valor": "R$ 150,00"
    }
  },
  {
    "recipient": "+5511988880000",
    "recipientType": "PHONENUMBER",
    "channelType": "SMS",
    "messageParams": {
      "nombre": "João",
      "valor": "R$ 90,00"
    }
  }
]

Campos

Campo	Obligatorio	Descripción
recipient	Sí	Número telefónico en formato internacional, con + (ej.: +5511999990000).
recipientType	No (por defecto PHONENUMBER)	Tipo de destinatario.
channelType	Sí	Usa SMS, igual que lo definido en la campaña.
messageParams	No	Variables usadas para personalizar el texto del mensaje (ej.: {{nombre}}, {{valor}}).
contextVariables	No	Variables adicionales de contexto, no usadas en el texto del mensaje.

Si ya proporcionaste fileUrl en la campaña (campaignType = BATCH), no necesitas llamar a /audiences manualmente — los destinatarios se cargan automáticamente desde el archivo.

Definir el mensaje — SET /messages/{campaignId}

Define el texto que se enviará por SMS.

Tipo de contenido: application/vnd.iris.activecampaign.message+json

Ejemplo de solicitud

{
  "channelType": "SMS",
  "messageContent": "Hola {{0}}, tu boleto de {{1}} vence mañana. Evita intereses, paga a tiempo.",
  "messageParams": ["nombre", "valor"]
}

Campos

Campo	Obligatorio	Descripción
channelType	Sí	Usa SMS.
messageContent	Sí	Texto del mensaje. Usa {{0}} para insertar los valores definidos en messageParams de cada destinatario.
messageParams	No	Lista con los nombres de los parámetros esperados en el texto (referencia/documentación).
messageTemplate / messageTemplateLanguage	No aplica para SMS	Usados solo en campañas de WhatsApp; para SMS, estos campos son ignorados.

Consejo: evita acentos y caracteres especiales en el texto del mensaje. Pueden aumentar el número de partes en que el SMS se divide por la operadora, encareciendo el envío.

Disparar la campaña — SET /dispatch

Inicia el envío efectivo de los mensajes de la campaña ya creada.

Tipo de contenido: application/vnd.iris.activecampaign.campaign+json (solo se consideran los campos abajo)

Ejemplo de solicitud

{
  "id": "campaign-sms-001",
  "isToUseLiteApi": false,
  "canSendWithOpenTicket": false
}

Campos

Campo	Obligatorio	Descripción
id	Sí	Id de la campaña creada en el paso 1.
isToUseLiteApi	No	Indica si el disparo debe usar la Lite API.
canSendWithOpenTicket	No	Permite enviar aunque el contacto tenga un servicio abierto.

Después del disparo, el envío se procesa de forma asíncrona: cada destinatario pasa por validación de cuenta, registro y envío del mensaje, con actualización de estado según el resultado de la entrega.

Flujo combinado — SET /campaign/full

Crea la campaña, registra la(s) audiencia(s), define el mensaje y dispara todo en una sola llamada. Usa para campañas del tipo INDIVIDUAL, BATCH.

Tipo de contenido: application/vnd.iris.activecampaign.full-campaign+json

Ejemplo de solicitud (campaña para un grupo de destinatarios vía SMS)

{
  "campaign": {
    "id": "campaign-sms-full-001",
    "name": "Campaña SMS Full - Promoción",
    "campaignType": "GROUP",
    "channelType": "SMS"
  },
  "audiences": [
    {
      "recipient": "+5511999990000",
      "recipientType": "PHONENUMBER",
      "channelType": "SMS",
      "messageParams": { "nombre": "Maria" }
    },
    {
      "recipient": "+5511988880000",
      "recipientType": "PHONENUMBER",
      "channelType": "SMS",
      "messageParams": { "nombre": "João" }
    }
  ],
  "message": {
    "channelType": "SMS",
    "messageContent": "Hola {{0}}, ¡aprovecha nuestra promoción hasta mañana!",
"messageParams": ["nombre"]
  },
  "dispatch": true
}

Campos

Campo	Obligatorio	Descripción
campaign	Sí	Datos de la campaña (mismos campos del paso 1).
audience	Condicional	Usado para un solo destinatario (campaignType = INDIVIDUAL).
audiences	Condicional	Lista de destinatarios (campaignType = BATCH).
message	Sí	Texto del mensaje SMS (mismos campos del paso 3).
dispatch	No (por defecto true)	Si es false, crea la campaña sin disparar automáticamente.

Flujo combinado dinámico — SET /campaign/full/v2

Variante del flujo combinado orientada a bases grandes: campañas BATCH (origen vía archivo CSV). Es la opción recomendada para volúmenes altos de destinatarios, pues procesa el origen de forma asíncrona.

Tipo de contenido: application/vnd.iris.activecampaign.full-campaign+json (mismo formato que /campaign/full)

Solo se aceptan campaignType = BATCH o USERSFILTER en este endpoint. Cualquier otro valor es rechazado.

Ejemplo de solicitud (campaña batch vía SMS, origen por archivo)

{
  "campaign": {
    "id": "campaign-sms-full-v2-001",
    "name": "Campaña SMS Full V2 - Base completa",
    "campaignType": "BATCH",
    "channelType": "SMS",
    "fileUrl": "https://storage.example.com/audiencias-sms.csv"
  },
  "message": {
    "channelType": "SMS",
    "messageContent": "Hola {{0}}, tu factura está disponible.",
"messageParams": ["nombre"]
  },
  "dispatch": true
}

Reglas importantes para el canal SMS

Convivencia con otros canales: habilitar el SMS no afecta el funcionamiento de campañas ya existentes en WhatsApp o Google RCS.

¿Necesitas más ayuda? Explora nuestros contenidos en la Blip Academy o Blip Community, mira tutoriales en nuestro canal de YouTube o resuelve tus dudas en nuestro canal de atención 😃