Saltar al contenido principal

Cómo enviar notificaciones mediante la API de ActiveCampaign en WhatsApp y RCS

  • Actualización
  1. Contexto
  2. Resumen de las solicitudes
  3. Entidades
  4. Envío de una campaña
    1. Campaña individual
    2. Campaña masiva con un solo envío
    3. Campaña masiva con audiencia dinámica (Beta)
  5. Resumen de la campaña
  6. Audiencia de la campaña
  7. Mensaje de la campaña 
  8. Informe de la campaña
  9. Ejemplos de envíos activos mediante la API de ActiveCampaign 
  10. Preguntas frecuentes (FAQ)

 

Contexto

Para realizar envíos de mensajes activos mediante la API de Blip, debes utilizar la API de Active Campaign. Esta permite integrar y automatizar tus campañas de marketing, administrar contactos, rastrear actividades y mucho más. Con esta API, puedes acceder a datos en tiempo real y manipularlos, personalizar flujos de trabajo automatizados y optimizar tus estrategias de marketing digital.

Este artículo contiene la documentación con los endpoints, parámetros de solicitud, ejemplos de solicitudes y respuestas esperadas para crear campañas de envío individual o masivo, mediante los canales de WhatsApp o RCS.

Antes de comenzar

  • La clave de acceso (Authorization/Key) utilizada en el encabezado de las solicitudes siempre debe corresponder al bot que tiene el canal conectado. Para localizar tu clave de acceso, consulta la documentación: ¿Cómo encontrar la API-KEY de mi bot? 

  • Si trabajas con una arquitectura que incluye varios subbots vinculados a un bot enrutador, la clave de acceso siempre debe ser la del bot enrutador. De lo contrario, utiliza la clave específica del subbot;

  • No es posible enviar mensajes activos en plantillas que tienen Flows;

 

Resumen de las solicitudes

Crear una nueva campaña:

  • /campaign/full

  • /campaign/v2

  • /audiences/v2/{CAMPAIGN_ID}

  • /audiences/v2/{CAMPAIGN_ID}/file

  • /dispatch/v2

Resumen de la campaña

  • /campaigns/summaries

  • /campaigns/{CAMPAIGN_ID}/summaries

Audiencia de la campaña

  • /audiences/{CAMPAIGN_ID}

Mensajes de la campaña

  • /messages/{CAMPAIGN_ID}

Informe de la campaña

  • /campaigns/{CAMPAIGN_ID}/reports

 

Entidades

La integración con la API de Active Campaign se basa en tres entidades principales: Campaña, Audiencia y Mensaje. 

 

Campaña

Una campaña se refiere a una acción de envío de mensajes de forma individual o masiva (Campaign Type) a un grupo específico de usuarios. Es una manera de llegar a un gran número de usuarios y comunicarse con ellos de forma automatizada y eficiente.

  • Mediante la plataforma, los desarrolladores y profesionales de marketing pueden crear campañas que envían mensajes a WhatsApp.

  • Es posible configurar el redireccionamiento del cliente a una etapa (StateId) del flujo del bot (FlowId) al responder un mensaje.

  • Las campañas se pueden configurar para enviar mensajes en tiempo real o programados (scheduled) para una hora específica.

Campos de la entidad de campaña

Campo Descripción Obligatorio
Id Identificador único de la campaña.
Name El nombre de la campaña. *
CampaignType El tipo de estrategia de envío de la campaña. Individual o masiva. *
Scheduled La fecha programada de la campaña. El formato de fecha esperado es UTF
MasterState Bot al que se dirigirá la campaña. Es decir, el bot en el que el cliente continuará el flujo después de responder al envío. El formato es IdDelBot@msging.net.
FlowId Identificación del flujo del bot. Es único por bot y se puede recuperar en las configuraciones del builder (obligatorio).
StateId Identificador del bloque, es decir, el estado específico al que se dirigirá el cliente después de responder. Puedes obtener esta información seleccionando el bloque en el Builder y haciendo clic en «Copiar Id».
ChannelType Es la definición del canal que se utilizará para el envío. Si no se informa, se utilizará el canal de WhatsApp de forma predeterminada. WhatsApp o GoogleRcs
SourceApplication Identificador de la herramienta de origen de la campaña. Si las campañas tienen varios orígenes, este campo puede ayudar a identificar dónde se creó cada una. WhatsApp o GoogleRcs
Tags Elementos personalizados que permiten agrupar las campañas. El contenido debe enviarse como un arreglo. WhatsApp o GoogleRcs

 

Audiencia

La audiencia es el público objetivo específico de la campaña de marketing, compuesto por una lista de personas que recibirán el mensaje.

  • Cada elemento contiene un número telefónico (recipient) y los parámetros correspondientes que se agregarán al mensaje (messageParams).

  • En el campo MessageParams, todos los valores (excepto el número telefónico) se guardarán en los datos adicionales del contacto (contact.extras). Esto permite incluir datos como edad, ubicación geográfica, preferencias de productos, historial de compras, entre otros, para lograr una segmentación y un análisis más eficaces. Los «datos adicionales de los contactos» son información adicional almacenada sobre cada contacto en un sistema de administración de contactos. Estos datos pueden incluir campos personalizados que registran información específica sobre cada contacto, para permitir una segmentación, personalización y análisis más eficaces de las campañas de marketing.
    Por ejemplo, además de los datos comunes como nombre y correo electrónico, puedes agregar campos adicionales para almacenar información como edad, ubicación geográfica, preferencias de productos, historial de compras, entre otros.

  • En el campo ContextVariables, todos los valores agregados se guardarán en el contacto como variables de contexto. Puedes utilizar estos valores dentro de un flujo con {{context.nomeVariavel}} o simplemente {{nomeVariavel}}. Si se trata de un objeto complejo, puedes usar {{nomeVariavel@empresaId}}

 Campos de la entidad de audiencia:

Campo Descripción Obligatorio
Recipient

Quién recibirá la campaña.

Debe incluir código de país + código de área + número telefónico. De lo contrario, se aplicará el formato MSISDN al número.

 *
MessageParams Parámetros que forman parte de la personalización del mensaje. Si existen, agrégalos como diccionario.
ContextVariables Parámetros que forman parte de la personalización de las variables de contexto del contacto. Si necesitas agregar variables de contexto, agrégalas como diccionario.

 

Mensaje

Representa el mensaje que se enviará en la campaña de marketing. Contiene el nombre de la plantilla (message Template) que incluye el contenido del mensaje y una lista de parámetros utilizados para personalizarlo con los valores específicos de cada destinatario (messageParams).

Campos de la entidad de mensaje

Campo Descripción Obligatorio
MessageTemplate Nombre de la plantilla del mensaje No existe plantilla cuando el canal es RCS
MessageParams

Parámetros que forman parte de la personalización del mensaje. 

Nota: El número de parámetros debe ser exactamente igual a la cantidad de parámetros del modelo de mensaje seleccionado.

Total de caracteres: 250

Se muestra en formato de arreglo
MessageContent Campo que contiene el mensaje cuando el canal es RCS
ChannelType Es la definición del canal que se utilizará para el envío. Si no se informa, se utilizará el canal de WhatsApp de forma predeterminada. WhatsApp o GoogleRcs

 

Envío de una campaña

La API de Active Campaign permite crear campañas para envíos individuales o masivos. Para crear y enviar una campaña, debes completar las entidades de campaña, audiencia y mensaje de acuerdo con las instrucciones anteriores.

Después de la solicitud, los siguientes campos aparecen en la respuesta:

Campo Descripción
Status El estado de envío de la campaña.
Created La fecha y hora de creación de la campaña.
FailedReason Motivo en caso de que el envío falle.

 

Campaña individual

Para realizar el envío inmediato de un mensaje individual, utiliza el endpoint /campaign/full configurado con "campaignType": "Individual". 

Debes enviar como «resource» un objeto que contenga las propiedades: campaign, audience y message.

  • Endpoint: POST https://{{sua_url}}.http.msging.net/commands

  • Encabezados (Headers):

    • Content-Type: application/json

    • Authorization: Key SUA_CHAVE_DE_AUTENTICACAO_AQUI

Solicitud para WhatsApp

{
    "id": "%commandId",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaign/full",
    "type": "application/vnd.iris.activecampaign.full-campaign+json",
    "resource": {
        "campaign": {
            "name": "Campanha individual completo e sem disparo",
            "campaignType": "Individual",
            "flowId": "{flowId}",
            "stateId": "{stateId}",
            //only for router
            "masterstate": "masterstate@msging.net",
            "channelType": "WhatsApp",
            "sourceApplication": "Postman",
            "tags": ["value1","valeu2","valeu3"
            ],
        },
        "audience": {
            "recipient": "+5531999...",
            "messageParams": {
                "1": "Repasse do novo Broadcast"
            },
"contextVariables": {
                 "cpf": "123456789001",
                 "cpf2": 1000111222,
                 "canUseTheseValues": false,
                 "specificContext": {
                     "foo": "111specififForFoo44431",
                     "bar": "222specififForBar55512"
                 }
        },
        "message": {
            "messageTemplate": "email_commerce_resposta",
            "messageParams": [
                "1"
            ],
            "channelType": "WhatsApp"
        }
    }
}

Solicitud para Google RCS

{
    "id": "%commandId",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaign/full",
    "type": "application/vnd.iris.activecampaign.full-campaign+json",
    "resource": {
        "campaign": {
            "name": "Campanha individual completo e sem disparo",
            "campaignType": "Individual",
            "flowId": "{flowId}",
            "stateId": "{stateId}",
            //only for router
            "masterstate": "masterstate@msging.net",
            "channelType": "GoogleRcs"
            "sourceApplication": "Postman",
            "tags": ["value1","valeu2","valeu3"
            ],
        },
        "audience": {
            "recipient": "+5531999...",
            "messageParams": {
                "1": "Repasse do novo Broadcast"
            },
        },
        "message": {
            "messageContent": "Exemplo de mensagem",
            "messageParams": [
                "1"
            ],
            "channelType": "GoogleRcs"
        }
    }
}

Respuesta

{
    "type": "application/vnd.iris.activecampaign.campaign+json",
    "resource": {
        "id": "37162f14-2d45...",
        "name": "Campanha individual completo e disparo",
        "campaignType": "INDIVIDUAL",
        "flowId": "{flowId}",
        "stateId": "{stateId}"
        "status": "processing",
        "created": "2021-10-22T14:14:02.310Z"
    },
    "method": "set",
    "status": "success",
    "id": "...",
    "from": "...",
    "to": "...",
    "metadata": {
        "#command.uri": "..."
    }
}

Si necesitas tener información adicional en cada contacto, puedes agregar parámetros dentro del objeto audience en la propiedad messageParams, con nombres como «extras1», «extras2» y así sucesivamente. No es necesario que se definan como «extra1» o «extra2»; lo importante es seguir el patrón de «clave» y «valor».

De esta manera:

"audience": {
    "recipient": "+55319...",
    "messageParams": {
        "1": "valor",
        "2": "dois",
        "extras1": " dados ocultos",
        "extras2": "que serão ser armazenadas no contato"
    }
}

Campaña masiva con envío único

Para enviar una campaña a varios contactos simultáneamente, el objeto resource debe tener las propiedades: campaign, audiences y message. El campo audiences debe ser un arreglo y la información definida en campaignType debe ser "Batch".

  • Endpoint: /campaign/full

Solicitud para WhatsApp

{
    "id": "%commandId",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaign/full",
    "type": "application/vnd.iris.activecampaign.full-campaign+json",
    "resource": {
        "campaign": {
            "name": "Campanha batch completo e sem disparo",
            "campaignType": "Batch",
            "flowId": "{flowId}",
            "stateId": "{stateId}",
            //only for router
            "masterstate": "masterstate@msging.net",
            "channelType": "WhatsApp"
            "sourceApplication": "Postman",
            "tags": ["value1","valeu2","valeu3"
            ],
        },
        "audiences": [
            {
                "recipient": "+55319...",
                "messageParams": {
                    "1": "Repasse do novo Broadcast"
                }
            },
            {
                "recipient": "+55319..",
                "messageParams": {
                    "1": "Repasse do novo Broadcast 2"
                },
            }
        ],
        "message": {
            "messageTemplate": "email_commerce_resposta",
            "messageParams": [
                "1"
            ],
            "channelType": "WhatsApp"
        }
    }
}

Solicitud para GoogleRcs

{
    "id": "%commandId",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaign/full",
    "type": "application/vnd.iris.activecampaign.full-campaign+json",
    "resource": {
        "campaign": {
            "name": "Campanha batch completo e sem disparo",
            "campaignType": "Batch",
            "flowId": "{flowId}",
            "stateId": "{stateId}",
            //only for router
            "masterstate": "masterstate@msging.net",
            "channelType": "GoogleRcs",
            "sourceApplication": "Postman",
            "tags": ["value1","valeu2","valeu3"
            ],
        },
        "audiences": [
            {
                "recipient": "+55319...",
                "messageParams": {
                    "1": "Repasse do novo Broadcast"
                }
            },
            {
                "recipient": "+55319..",
                "messageParams": {
                    "1": "Repasse do novo Broadcast 2"
                },
            }
        ],
        "message": {
            "messageContent": "Mensagem de teste",
            "messageParams": [
                "1"
            ],
            "channelType": "GoogleRcs"
        }
    }
}

Respuesta

{
    "type": "application/vnd.iris.activecampaign.campaign+json",
    "resource": {
        "id": "37162f14-2d45-...",
        "name": "Campanha individual completo e disparo",
        "campaignType": "INDIVIDUAL",
        "flowId": "{flowId}",
        "stateId": "{stateId}"
        "status": "processing",
        "created": "2021-10-22T14:14:02.310Z"
    },
    "method": "set",
    "status": "success",
    "id": "...",
    "from": "...",
    "to": "...",
    "metadata": {
        "#command.uri": "..."
    }
}

Campaña masiva con audiencia dinámica (Beta)

Este enfoque implica utilizar varias solicitudes: una para crear la campaña, varias para agregar la audiencia y, posteriormente, una última para enviar la campaña. A diferencia de la campaña masiva con envío único, en la que todo se realiza en una sola solicitud, el flujo dinámico ofrece mayor control y flexibilidad al separar las etapas en diferentes solicitudes.

 Con el flujo dinámico, puedes tener un control más detallado sobre cada etapa del proceso de la campaña.

Creación de la campaña

  • Endpoint: /campaign/v2

Solicitud para WhatsApp

{
    "id": "{{$guid}}",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaign/v2",
    "type": "application/vnd.iris.activecampaign.campaign-dynamic+json",
    "resource": {
        "campaign": {
            "name": "Campanha em Massa postman {{$guid}}",
            "campaignType": "Batch",
            "flowId": "{{flowId}}",
            "stateId": "{{stateId}}"
            //only for router
            "masterstate": "masterstate@msging.net",
            "channelType": "WhatsApp",
            "sourceApplication": "Postman",
            "tags": ["value1","valeu2","valeu3"],
        },
        "message": {
            "messageTemplate": "{{messageTemplate}}",
            "channelType": "WhatsApp"
        }
    }
}

Solicitud para GoogleRcs

{
    "id": "{{$guid}}",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaign/v2",
    "type": "application/vnd.iris.activecampaign.campaign-dynamic+json",
    "resource": {
        "campaign": {
            "name": "Campanha em Massa postman {{$guid}}",
            "campaignType": "Batch",
            "flowId": "{{flowId}}",
            "stateId": "{{stateId}}"
            //only for router
            "masterstate": "masterstate@msging.net",
            "channelType": "GoogleRcs",
            "sourceApplication": "Postman",
            "tags": ["value1","valeu2","valeu3"],
        },
        "message": {
            "messageContent": "Exemplo de mensagem",
            "channelType": "GoogleRcs"
        }
    }
}

Respuesta

{
    "type": "application/vnd.iris.activecampaign.campaign+json",
    "resource": {
        "id": "ffc99160-5182...",
        "name": "Campanha em Massa",
        "campaignType": "BATCH",
        "flowId": "f7bfd815-1327...",
        "stateId": "onboarding",
        "status": "new",
        "created": "2024-06-03T17:21:05.577Z"
    },
    "method": "set",
    "status": "success",
    "id": "...",
    "from": "...",
    "to": "...",
    "metadata": {
        "traceparent": "...",
        "#command.uri": "..."
    }
}

 

Inclusión de audiencia

La inclusión de audiencia se puede realizar tantas veces como sea necesario, limitada únicamente por la cantidad de audiencia aceptada en la campaña.

Envío de una lista en la solicitud

  • Endpoint: /audiences/v2/{{id de la campaña creada}}

Solicitud

{
    "id": "{{$guid}}",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/audiences/v2/{{resource.id}}",
    "type": "application/vnd.lime.collection+json",
    "resource": {
     "itemType": "application/vnd.iris.activecampaign.audience+json",
     "items": [
            {"recipient": "+5520900000001"},
            {"recipient": "+5520900000002"},
            {"recipient": "+5520900000003"}
        ]
    }
}

Respuesta

{
    "type": "application/vnd.iris.activecampaign.audience-json+json",
    "resource": {
     "": [],
     "TotalValidNumbers": 3,
     "TotalInvalidNumbers": 0,
     "Status": "Success"
    },
    "method": "set",
    "status": "success",
    "id": "...",
    "from": "...",
    "to": "...",
    "metadata": {
     "traceparent": "...",
     "#command.uri": "..."
    }
}

Envío de una lista mediante un archivo CSV

  • Endpoint: /audiences/v2/{{id de la campaña creada}}

Solicitud

{
    "id": "{{$guid}}",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/audiences/v2/{{create_campaign}}/file",
    "type": "application/vnd.iris.activecampaign.audience-file+json",
    "resource": {
     "url": "{{create_bach_file}}"
    }
}

Respuesta

{
    "type": "application/vnd.iris.activecampaign.audience-json+json",
    "resource": {
     "": [],
     "TotalValidNumbers": 3,
     "TotalInvalidNumbers": 0,
     "Status": "Success"
    },
    "method": "set",
    "status": "success",
    "id": "e3a955cb-d2bb-42f5-892d-430a7355872a",
    "from": "postmaster@activecampaign.msging.net/#msging-application-activecampaign-c76f85944-526dw",
    "to": "whatsappcloudapihmg@msging.net/!msging-server-l5xk4-mibif7au",
    "metadata": {
     "traceparent": "00-5ad953eb416091184339a794fe08814e-d15f81f9a03b326f-01",
     "#command.uri": "lime://whatsappcloudapihmg@msging.net/audiences/v2/00a54137-b1f4-483b-99aa-f7c854b8146d/file"
    }
}

Observaciones

Para informar las variables de contexto en el CSV, puedes enviar un JSON escapado, como en el ejemplo, con la columna titulada #contextvariables#

Ejemplo: 

{\"cpf\":\"123456789001\",\"cpf2\":1000111222,\"canUseTheseValues\":false,\"specificContext\":{\"foo\":\"111specififForFoo44431\",\"bar\":\"222specififForBar55512\"}
 

Envío de la campaña

Esta es la acción de enviar la campaña que se creó y cuya audiencia ya se completó. 

Nota: Una vez enviada la campaña, ya no es posible incluir nuevas audiencias.

  • Endpoint: /dispatch/v2

Solicitud

{
    "id": "{{$guid}}",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/dispatch/v2",
    "type": "application/vnd.iris.activecampaign.campaign+json",
    "resource": {
     "id": "{{create_campaign}}"
    }
}

Respuesta

{
    "method": "set",
    "status": "success",
    "id": "...",
    "from": "...",
    "to": "...",
    "metadata": {
     "traceparent": "...",
     "#command.uri": "..."
    }
}

 

Resumen de la campaña

Mediante esta funcionalidad, tendrás acceso a información importante sobre tus campañas, lo que permite realizar un análisis detallado del desempeño y el estado del público objetivo.

Nota: Si no se informa ningún filtro, se devolverán todas las campañas creadas en la fecha informada o posteriormente. 

La solicitud puede recibir los siguientes datos como filtro:

Campo Descripción
SourceApplication Origen de la campaña, por ejemplo: Portal, Desk, Broadcast-Plugin o API.
CampaignSender Quién envió la campaña.
Created La fecha que determina qué campañas se incluirán en la respuesta de la solicitud. Solo se considerarán las campañas creadas en esta fecha.

Si no se informa el filtro de creación, se devolverán todas las campañas creadas en la fecha informada o posteriormente.

La respuesta de la solicitud está compuesta por: 

Campo Descripción
id Identificador de la campaña
messageTemplate Nombre de la plantilla del mensaje
name Nombre de la campaña
sendDate Fecha de envío y estado del público objetivo
FlowId Identificación del flujo del bot.
StateId Identificador del bloque enviado
statusAudience El estado de la audiencia está compuesto por una lista con el estado de procesamiento del destinatario y la identidad

Requisitos

Es necesario tener al menos una campaña registrada para el bot.

Comandos

Obtener el resumen de las campañas

Al utilizar esta solicitud, se devolverán las campañas que cumplen con los criterios del filtro informado.

  • Endpoint: /campaigns/summaries

Solicitud

{
    "id": "{commandId}",
    "to": "postmaster@activecampaign.msging.net",
    "method": "get",
    "uri": "/campaigns/summaries?created=2022-06-26T18%3A02%3A40.000Z&SourceApplication=Portal&CampaignSender=user.sender@take.net"
}

Respuesta

{
    "type": "application/vnd.lime.collection+json",
    "resource": {
     "total": 1,
     "itemType": "application/vnd.iris.activecampaign.campaignsummary+json",
     "items": [
            {
             "id": "{id}",
             "messageTemplate": "email_commerce_resposta",
             "sendDate": "2022-06-14T18:02:40.300Z",
             "statusAudience": [
                    {
                     "RecipientIdentity": "555555555555@wa.gw.msging.net",
                     "Status": "FAILED",
                     "ReasonCode": 61,
                     "ReasonDescription": "An unexpected error occurred while set transaction."
                    },
                    {
                     "RecipientIdentity": "555555555551@wa.gw.msging.net",
                     "Status": "READ"
                    }
                ]
            }
        ]
    },
    "method": "get",
    "status": "success",
    "id": "...",
    "from": "postmaster@activecampaign.msging.net/#...",
    "to": "whatsapp2@msging.net/...",
    "metadata": {
     "#command.uri": "...",
     "uber-trace-id": "..."
    }
}

 

Obtener el resumen de una campaña específica

Para obtener el resumen de una campaña específica, puedes usar esta solicitud proporcionando el ID de la campaña. Esto te permitirá obtener información detallada sobre esa campaña, como la plantilla utilizada, la fecha de envío y el estado del público objetivo.

Endpoint:  /campaigns/{Id de la campaña}/summaries

Requisitos

  • El ID de la campaña

Solicitud

{
    "id": "%commandId",
    "to": "postmaster@activecampaign.msging.net",
    "method": "get",
    "uri": "/campaigns/{Id da campanha}/summaries"
}

Respuesta

{
  "type": "application/vnd.lime.collection+json",
  "resource": {
   "total": 1,
   "itemType": "application/vnd.iris.activecampaign.campaignsummary+json",
   "items": [
          {
           "id": "{id}",
           "messageTemplate": "email_commerce_resposta",
           "sendDate": "2022-06-14T18:02:40.300Z",
           "statusAudience": [
                  {
                   "RecipientIdentity": "555555555555@wa.gw.msging.net",
                   "Status": "FAILED",
                   "ReasonCode": 61,
                   "ReasonDescription": "An unexpected error occurred while set transaction."
                  },
                  {
                   "RecipientIdentity": "555555555551@wa.gw.msging.net",
                   "Status": "READ"
                  }
              ]
          }
      ]
  },
  "method": "get",
  "status": "success",
  "id": "...",
  "from": "postmaster@activecampaign.msging.net/...",
  "to": "whatsapp2@msging.net/...",
  "metadata": {
   "#command.uri": "...",
   "uber-trace-id": "..."
  }
}

 

Audiencia de la campaña

La audiencia de una campaña es el público objetivo específico de la campaña de marketing. Está compuesta por un grupo de personas, cuya selección puede basarse en criterios demográficos, conductuales u otros factores relevantes.

Con nuestra API, puedes obtener información sobre la audiencia de una campaña.

Campos de la entidad de audiencia

Campo Descripción Obligatorio
Recipient El número de teléfono del destinatario del mensaje. Solo se considerarán números de teléfono válidos. *
MessageParams El diccionario con los nombres y valores de los parámetros de la plantilla del mensaje.

Campos de la respuesta

Campo  Descripción
Total Total de la audiencia
Items Lista que especifica la audiencia

Los elementos están compuestos por:

Campo Descripción
CampaignId ID de la campaña
Recipient El destinatario del mensaje
RecipientType El tipo correspondiente a lo enviado en recipient, por ejemplo, si es un número celular
ChannelType El canal en el que se alcanzó al público
MessageParams

Parámetros que se enviaron en el mensaje. 

El límite máximo es de 250 caracteres.
Status El estado del envío
AudienceStatus El estado de envío del público objetivo.
ValidatedAccount La cuenta validada del público objetivo.
Received La fecha y hora en que se recibió el mensaje.
Read La fecha y hora en que se leyó el mensaje.
Failed La fecha y hora en que falló el mensaje.
ReasonCode El código del motivo de la falla.
ReasonDescription La descripción del motivo de la falla.

 

Obtener la audiencia de la campaña

  • Endpoint: /audiences/{Id de la campaña}

Podemos usar este endpoint para obtener la audiencia de una campaña específica. 

Requisitos

  • El ID de la campaña.

Solicitud

{
    "id": "%commandId",
    "to": "postmaster@activecampaign.msging.net",
    "method": "get",
    "uri": "/audiences/{id da campanha}",
}

Respuesta

{
  "type": "application/vnd.lime.collection+json",
  "resource": {
   "total": 1,
   "itemType": "application/vnd.iris.activecampaign.audience+json",
   "items": [
          {
           "OwnerIdentity": "whatsappcloudapi@msging.net",
           "CampaignId": "....",
           "recipient": "+5531...",
           "recipientType": "PhoneNumber",
           "channelType": "WHATSAPP",
           "messageParams": {
               "1": "valor",
               "2": "dois",
               "extras1": " dados ocultos",
               "extras2": "que serão ser armazenadas no contato"
              },
           "status": "VALID",
           "validatedAccount": "553197...@wa.gw.msging.net",
           "processed": "2024-05-16T18:54:31.930Z",
           "received": "2024-05-16T18:54:39.290Z",
           "read": "2024-05-16T18:55:40.980Z"
          }
      ]
  },
  "method": "get",
  "status": "success",
  "id": "%commandId",
  "from": "...",
  "to": "...": {
   "traceparent": "...",
   "#command.uri": "..."
  }
}

 

Mensaje de la campaña 

Campos de la plantilla del mensaje

Campo Descripción Obligatorio
ChannelType

El tipo de canal. 

"WhatsApp" = Estándar o

“GoogleRcs”
MessageTemplate El nombre de la plantilla del mensaje. Se usa con el canal de WhatsApp
MessageContent El contenido del mensaje Se usa con el canal RCS
MessageTemplateLanguage* El idioma de la plantilla del mensaje.
MessageParams La lista de nombres de parámetros. Este valor se usa para validar el número de parámetros de la audiencia cuando la campaña es individual.

*ActiveCampaign define Portugués (PT-BR) como idioma predeterminado. Por lo tanto, al enviar una notificación activa mediante la API en otro idioma, es obligatorio especificar el campo messageTemplateLanguage.

Campos de la respuesta

La respuesta está compuesta por:

Campo Descripción
Total Total de mensajes
Items Lista de los mensajes enviados

El campo Items está compuesto por:

Campo Descripción
ChannelType Tipo de canal
MessageTemplate Nombre de la plantilla del mensaje
MessageParams Parámetros que se enviaron en el mensaje.

 

Obtener los mensajes de una campaña

  • Endpoint: /messages/{campaignId}

Requisitos

  • El ID de la campaña

Solicitud

{
    "id": "%commandId",
    "to": "postmaster@activecampaign.msging.net",
    "method": "get",
    "uri": "/messages/{CAMPAIGN_ID}",
}

Respuesta

{
  "type": "application/vnd.lime.collection+json",
  "resource": {
    "total": 1,
    "itemType": "application/vnd.iris.activecampaign.message+json",
    "items": [
      {
     "channelType": "WHATSAPP",
     "messageTemplate": "email_commerce_resposta",
     "messageParams": "1"
      }
    ]
  },
  "method": "get",
  "status": "success",
  "id": "%id",
  "from": "postmaster@activecampaign.msging.net/#note-mc159",
  "to": "whatsapp1@msging.net/default",
  "metadata": {
    "#command.uri": "lime://whatsapp1@msging.net/messages/{CAMPAIGN_ID}"
  }
}


Informe de la campaña

Para obtener un informe del estado de una campaña, puedes usar esta solicitud. El informe incluye información sobre la plantilla del mensaje utilizada en la campaña y el destino de redirección. Esto te permitirá tener una visión integral del desempeño y los resultados de la campaña, lo que ayudará a tomar decisiones para optimizarla posteriormente.

Requisitos

  • ID de la campaña

Campos de la respuesta

La respuesta está compuesta por:

Campo Descripción
Id ID de la campaña
Name Nombre de la campaña
MessageTemplate Plantilla del mensaje elegida para la campaña.
MasterState El estado principal de la campaña, si el bot es un enrutador.
FlowId ID del flujo de la campaña.
StateId ID del estado de la campaña.
StateName Nombre del estado de la campaña.
AttendanceRedirect Correo electrónico del agente al que se redirigirá la campaña, si se eligió esta opción.
CampaignSender Correo electrónico de quien envió la campaña.
SendDate Fecha en que se envió la campaña.
StatusAudience Una lista de estados de los números de la campaña.

La propiedad StatusAudience es una lista en la que cada elemento está compuesto por:

Campo Descripción
RecipientIdentity Número del contacto. Si no ocurrió ningún error durante el preprocesamiento de este número, se mostrará el número validado proporcionado por WhatsApp. De lo contrario, se mostrará el número proporcionado en el archivo del público objetivo o en la solicitud al momento de crear la campaña.
Status El estado del público objetivo al momento de la solicitud.
ReasonCode El código del motivo de la falla del público objetivo.
ReasonDescription La descripción del motivo de la falla del público objetivo.
Processed La fecha y hora en que se envió el público objetivo al usuario final.
Received La fecha y hora en que el usuario final recibió el público objetivo.
Read La fecha y hora en que el usuario final leyó el público objetivo.
Failed La fecha y hora en que falló el público objetivo.
NumberStatus El estado de procesamiento del público objetivo.

 

Obtener el informe de una campaña específica

  • Endpoint: /campaigns/{campaignId}/reports

Solicitud

{
    "id": "%commandId",
    "to": "postmaster@activecampaign.msging.net",
    "method": "get",
    "uri": "/campaigns/{campaignId}/reports?shouldHaveStateName=true"
}

Respuesta

{
  "type": "application/vnd.iris.activecampaign.campaignsummary+json",
  "resource": {
    "id": "#campaignId",
    "name": "%name",
    "messageTemplate": "berlin_fttr_monitoramento_",
    "flowId": "%flowId",
    "stateName": "welcome",
    "stateId": "%stateId8",
    "sendDate": "2022-11-22T19:58:21.050Z",
    "statusAudience": [
      {
     "recipientIdentity": "%Number of the contact@wa.gw.msging.net",
     "status": "PROCESSED",
     "processed": "2022-11-22T19:58:24.050Z",
     "numberStatus": "VALID"
      },
      {
     "recipientIdentity": "%Number of the contac 2@wa.gw.msging.net",
     "status": "PROCESSED",
     "processed": "2022-11-22T19:58:23.910Z",
     "numberStatus": "VALID"
      },
      {
     "recipientIdentity": "+%Number of the contac 3",
     "status": "FAILED",
     "reasonCode": 1505,
     "reasonDescription": "Invalid recipient for WhatsApp channel.",
     "failed": "2022-11-22T07:57:44.000Z",
     "numberStatus": "INVALID"
      }
    ]
  },
  "method": "get",
  "status": "success",
  "id": "%id",
  "from": "postmaster@activecampaign.msging.net/#hmg-az-iris2",
  "to": "whatsapp2@msging.net/default",
  "metadata": {
    "#command.uri": "lime://whatsapp2@msging.net/campaigns/{campaignId}/reports",
    "uber-trace-id": " %trace-id"
  }
}

 

Ejemplos de envíos activos mediante la API de ActiveCampaign 

Consulta nuestra guía de ejemplos de solicitudes para cada tipo de plantilla: Guía técnica: Ejemplos de envíos activos mediante la API de ActiveCampaign
 

Preguntas frecuentes (FAQ)

¿Es posible realizar un envío mediante v2 con programación? 

Sí, existe esta posibilidad. Solo debes informar el campo ‘Scheduled’ en el formato ‘aaaa-MM-dd hh:mm’ de la entidad Campaña. 

¿Es posible cancelar una campaña programada? 

Puedes cancelar una programación enviando un comando DELETE. Sustituye {campaignId} por el ID de la campaña correspondiente al mensaje programado que deseas eliminar.
La campaña se eliminará y la programación se cancelará.

Cuerpo de la solicitud:

{ 
  "id": "{{$guid}}",
  "to": "postmaster@activecampaign.msging.net",
  "method": "delete",
  "uri": "/campaigns/{campaignId}}"
}

Después de programar una campaña, ¿es posible agregar más datos a la programación? 

No es posible cambiar (agregar o editar) los valores de una campaña cuando está programada. Para hacerlo, es necesario eliminar la programación y crear una campaña nueva.

¿El envío manual de campañas genera evidencia de que el mensaje fue enviado? 

Para realizar el envío manual de un mensaje activo, es posible programar o realizar los envíos mediante Growth, y toda la información se registrará en la pantalla, tanto la de los mensajes que fallaron como la de los que se recibieron o leyeron:

¿Es posible realizar un envío sin dirigirlo a un punto específico del flujo?

Sí, el estado del usuario se define mediante StateId y FlowId. Solo debes omitir estas líneas en tu envío para que, al responder, el cliente sea dirigido al bloque Inicio del bot principal.

 

 

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

Artículos relacionados