Saltar al contenido principal

Guía de Migración: /messages → /campaign/full (API Active Campaign Growth)

  • Actualización
  1. Visión general de los dos enfoques
  2. Diferencias conceptuales principales
  3. Ejemplo práctico
  4. Mapeo de los tipos de componentes de la plantilla para claves de messageParams
  5. Campos sin equivalente
  6. Campos opcionales de la campaña
  7. Estructura de la respuesta
  8. Checklist de migración
  9. Documentación de apoyo

 

Este documento describe cómo migrar el envío de mensajes con plantilla WhatsApp del endpoint LIME /messages a la API Active Campaign Growth utilizando el endpoint /campaign/full.

 

Visión general de los dos enfoques

Aspecto /messages (directo) /campaign/full (Active Campaign)
Endpoint HTTP POST .../messages POST .../commands
Primitiva LIME Mensaje Comando (method: set)
Destino Identidad del usuario (5592...@wa.gw.msging.net) postmaster@activecampaign.msging.net
Content-Type application/json application/vnd.iris.activecampaign.full-campaign+json
Estructura de la plantilla Árbol completo de componentes WhatsApp Nombre de la plantilla + parámetros nombrados
Redireccionamiento de flujo No Opcional (flowId / stateId)
Seguimiento / reporte Ninguno Reporte completo de la campaña, estado por destinatario
Programación No Sí (scheduled)
Tipo de campaña — Siempre Individual en este escenario
Auditoría Ninguna Campaña almacenada con estado por destinatario

 

Diferencias conceptuales principales

1. Endpoint HTTP y primitiva de protocolo

Esta es la diferencia más importante entre los dos enfoques.

Antes (/messages) — el payload es un mensaje LIME enviado al endpoint /messages:

POST https://{{contract.id}}.http.msging.net/messages HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}

Después (/campaign/full) — el payload es un comando LIME enviado al endpoint /commands:

POST https://{{contract_id}}.http.msging.net/commands HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}

En el protocolo LIME, mensajes se usan para intercambio directo de contenido entre el bot y un usuario final. Comandos se usan para interactuar con extensiones y servicios de la plataforma, como Active Campaign. Por eso, además de cambiar la dirección de destino, toda la estructura del sobre cambia: el campo content da lugar a method, uri y resource.

2. Estructura de la plantilla

La segunda gran diferencia es la forma en que se expresan los parámetros de la plantilla.

Antes (/messages) — árbol completo de componentes WhatsApp:

{
  "type": "template",
  "template": {
    "language": {
      "policy": "deterministic",
      "code": "pt_BR"
    },
    "name": "dia_do_doce_v11",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://example.com/image.jpg"
            }
          }
        ]
      }
    ]
  }
}

Después (/campaign/full) — nombre de la plantilla + parámetros nombrados:

"message": {
  "messageTemplate": "dia_do_doce_v11",
  "messageTemplateLanguage": "pt_BR",
  "messageParams": ["image"],
  "channelType": "WhatsApp"
}

El servicio Active Campaign reconstruye el árbol de componentes WhatsApp internamente a partir de los metadatos de la plantilla y de los valores proporcionados en audience.messageParams. Ya no es necesario describir la estructura de los componentes.

3. Vinculación de parámetros

En el enfoque /messages, los valores de los parámetros están incrustados directamente en el árbol de componentes. En /campaign/full, los valores se informan por separado por destinatario en el objeto audience.messageParams (diccionario clave → valor), mientras que message.messageParams contiene solo la lista de nombres de las claves (el esquema), usada para validar que cada destinatario tenga los valores necesarios.

Qué Ubicación anterior Nueva ubicación
Nombre de la plantilla content.template.name message.messageTemplate
Código del idioma content.template.language.code message.messageTemplateLanguage
URL de la imagen del header components[header].parameters[].image.link audience.messageParams["image"]
Variables de texto del body components[body].parameters[].text audience.messageParams["1"], ["2"], …
Sufijo de URL de botón dinámico components[button].parameters[].text audience.messageParams["url_suffix"]
Teléfono del destinatario Campo to (numero@wa.gw.msging.net) audience.recipient (formato E.164)

 

Ejemplo práctico

Antes — envío vía /messages

POST https://{{contract.id}}.http.msging.net/messages HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}


{
  "id": "activecampaign:335924e6-6831-4ddf-b400-2296cf6c94cc",
  "to": "5592994397150@wa.gw.msging.net",
  "type": "application/json",
  "content": {
    "type": "template",
    "template": {
      "language": {
        "policy": "deterministic",
        "code": "pt_BR"
      },
      "name": "dia_do_doce_v11",
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "image",
              "image": {
                "link": "https://www.iped.com.br/_upload/galleries/2015/05/19/organizao-pblica-555b72de0abc9.jpg"
              }
            }
          ]
        }
      ]
    }
  }
}

Características:

  • Mensaje directo, no se crea ningún registro de campaña.
  • Sin redireccionamiento a flujo del bot.
  • Sin seguimiento de entrega.
  • Idioma de la plantilla pt_BR con política deterministic.

Después — envío vía /campaign/full

POST https://{{contract_id}}.http.msging.net/commands HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}


{
  "id": "{{$guid}}",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/campaign/full",
  "type": "application/vnd.iris.activecampaign.full-campaign+json",
  "resource": {
    "campaign": {
      "name": "Dia do Doce - individual",
      "campaignType": "Individual",
      "channelType": "WhatsApp",
      "sourceApplication": "MyApp"
    },
    "audience": {
      "recipient": "+5592994397150",
      "messageParams": {
        "image": "https://www.iped.com.br/_upload/galleries/2015/05/19/organizao-pblica-555b72de0abc9.jpg"
      }
    },
    "message": {
      "messageTemplate": "dia_do_doce_v11",
      "messageTemplateLanguage": "pt_BR",
      "messageParams": ["image"],
      "channelType": "WhatsApp"
    }
  }
}

Cambios notables:

  1. Endpoint HTTP cambió de .../messages a .../commands.

  2. to cambió a postmaster@activecampaign.msging.net.

  3. Se añadieron method: "set" y uri: "/campaign/full" — obligatorios en comandos LIME.

  4. El content con el árbol de componentes fue removido; en su lugar entran campaign, audience y message dentro de resource.

  5. La URL de la imagen fue movida a audience.messageParams["image"].

  6. El teléfono del destinatario fue movido a audience.recipient en formato E.164 (con código de país, sin el sufijo @wa.gw.msging.net).

  7. flowId / stateId son omitidos intencionalmente — el mensaje se envía sin redirigir al usuario a ningún flujo del bot.

  8. campaignType es siempre Individual en este escenario (envío para un solo destinatario por llamada).

Importante: message.messageParams es un arreglo de nombres de claves (strings), no de valores. Define qué claves de audience.messageParams serán usadas como parámetros de la plantilla. El servicio Active Campaign utiliza esta lista para validar si el destinatario tiene todos los valores necesarios antes del envío.

 

Mapeo de los tipos de componentes de la plantilla a claves de messageParams

Cuando la plantilla tiene múltiples tipos de componentes, todos los valores de parámetros se aplanan en el diccionario audience.messageParams. Usa nombres descriptivos para las claves; el servicio los mapea en el orden de declaración dentro de cada tipo de componente.

Tipo de componente Tipo de parámetro Meta Nombre de clave sugerido Ejemplo de valor
Header – imagen image "image" "https://cdn.example.com/banner.jpg"
Header – video video "video" "https://cdn.example.com/video.mp4"
Header – documento document "document" "https://cdn.example.com/file.pdf"
Body – variable de texto {{1}} text "1" o cualquier etiqueta "João"
Body – variable de texto {{2}} text "2" o cualquier etiqueta "Premium"
Botón – sufijo de URL dinámica text "url_suffix" "/promo/XYZ123"

Los nombres de las claves son libres, siempre que sean consistentes entre audience.messageParams (valores) y message.messageParams (esquema). El orden en message.messageParams debe corresponder al orden de los parámetros en la plantilla registrada en Meta.

 

Campos sin equivalente

Los siguientes campos del enfoque /messages no tienen equivalente en /campaign/full porque se manejan automáticamente o no aplican:

Campo antiguo Motivo de la ausencia
content.template.language.policy Siempre deterministic — no es configurable vía Active Campaign
id con prefijo activecampaign: El servicio de campaña genera sus propios IDs de correlación
to con sufijo @wa.gw.msging.net Sustituido por audience.recipient en formato E.164

 

Campos opcionales de la campaña

Estos campos están ausentes en el ejemplo mínimo anterior, pero están disponibles para enriquecimiento:

Campo Dónde Finalidad
flowId + stateId campaign Redirige al usuario a un estado específico del bot al responder
masterState campaign Obligatorio cuando se usa arquitectura con bot enrutador
scheduled campaign Programa el envío para una fecha/hora futura (yyyy-MM-dd hh:mm)
tags campaign Etiquetas arbitrarias para filtrar/agrupar campañas
contextVariables audience Variables guardadas en el contexto del contacto (accesibles como {{nombreVariable}} en los flujos)

 

Estructura de la respuesta

En caso de éxito, el servicio responde con un documento Campaign:

{
  "type": "application/vnd.iris.activecampaign.campaign+json",
  "resource": {
    "id": "37162f14-2d45-...",
    "name": "Dia do Doce - individual",
    "campaignType": "INDIVIDUAL",
    "status": "processing",
    "created": "2026-07-02T14:00:00.000Z"
  },
  "method": "set",
  "status": "success"
}

Utilice el id retornado para consultar el estado, los detalles de la audiencia y los reportes de entrega:

GET /campaigns/{id}/reports

GET /audiences/{id}

GET /campaigns/summaries

 

Lista de verificación para la migración

  • Cambiar el endpoint HTTP de .../messages a .../commands

  • Cambiar el to de la identidad del usuario a postmaster@activecampaign.msging.net

  • Cambiar el tipo del sobre a application/vnd.iris.activecampaign.full-campaign+json

  • Agregar method: "set" y uri: "/campaign/full"

  • Mover el nombre de la plantilla a message.messageTemplate

  • Mover el código del idioma a message.messageTemplateLanguage (obligatorio si es diferente de pt_BR)

  • Convertir los valores de los parámetros de los componentes a un diccionario plano en audience.messageParams

  • Listar los nombres de las claves en message.messageParams (array, mismo orden de los parámetros de la plantilla registrada en Meta)

  • Convertir el destinatario de numero@wa.gw.msging.net a formato E.164 (ej.: +5592994397150)

  • Definir campaign.campaignType como Individual

  • Omitir flowId / stateId si no se desea redireccionamiento a flujo del bot

  • Usar messageTemplate, no messageContent, para WhatsApp

 

Documentación de apoyo


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

Artículos relacionados