Índice:
Introducción
La API de Active Campaign permite la integración y automatización de tus campañas de marketing, gestión de contactos, seguimiento de actividades y mucho más. Con nuestra API, puedes acceder y manipular datos en tiempo real, personalizar flujos de trabajo automatizados y optimizar tus estrategias de marketing digital.
En esta guía, encontrarás la documentación completa sobre todos los puntos finales, parámetros de solicitud, ejemplos de solicitudes y respuestas esperadas. Aprende a explorar los recursos y aprovecha todas las funcionalidades disponibles.
Resumen de las solicitudes
Crear 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
Público 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
Campaña
Una campaña se refiere a una acción de envío de mensajes de forma individual o masiva (CampaignType) a un grupo específico de usuarios. Es una forma de alcanzar y comunicarse con una gran cantidad de usuarios de forma automatizada y eficiente.
A través de la plataforma BLiP, los desarrolladores y profesionales de marketing pueden crear campañas que envían mensajes a WhatsApp y configurar el redireccionamiento del cliente a una etapa (StateId) del flujo del bot (FlowId) al responder un mensaje.
Las campañas pueden configurarse para enviar mensajes en tiempo real o programados (scheduled) para un horario específico.
Audiencia
La audiencia es el público objetivo específico de la campaña de marketing. Está compuesta por una lista de individuos que recibirán el mensaje.
Cada ítem contiene un número de teléfono (recipient) y los parámetros relacionados con él que se agregarán al mensaje (messageParams).
Mensaje
La entidad "mensaje" representa el mensaje que será enviado en la campaña de marketing. Contiene el nombre de la plantilla del mensaje (messageTemplate) que incluye el contenido del mensaje y una lista de parámetros que se usarán para personalizar el mensaje con los valores específicos de cada destinatario (messageParams).
Enviando una campaña
La API de Active Campaign permite la creación de campañas para envío individual o en lote.
Campos de la entidad de la 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 para la programación de la campaña. El formato de fecha esperado es UTF. | |
MasterState |
Estado del enrutador hijo para el flujo de redirección. Este parámetro es obligatorio si el bot es del tipo enrutador. (Ejemplo: child@msging.net) |
|
FlowId | Identificación del flujo del bot. Es único por bot y puede ser recuperado dentro de la configuración del builder. | * |
StateId | El StateId es el identificador del estado específico en el que se encuentra el bot dentro del flujo de conversación. | * |
ChannelType | Es la definición del canal que se utilizará en el envío. Si no se especifica, se utilizará el canal de WhatsApp como predeterminado. |
o GoogleRcs |
La información de la audiencia es:
Campo | Descripción | Obligatorio |
Recipient | Quién recibirá la campaña. Debe tener DDI + DDD + número de teléfono. El formato MSISDN se aplicará al número, en caso contrario. | * |
MessageParams | Parámetros que forman parte de la personalización del mensaje. Si los hay, agréguelos como diccionario. |
En el campo MessageParams de la entidad Audiencia, todos los valores, excepto el número de teléfono, se guardarán en los extras del contacto. Esto significa que puedes incluir parámetros adicionales y personalizados en el campo MessageParams, y esos valores se almacenarán en contact.extras.
Los 'datos extras de los contactos' se refieren a información adicional almacenada sobre cada contacto en un sistema de gestión de contactos. Estos datos extras pueden incluir campos personalizados que capturan información específica sobre cada contacto, permitiendo una segmentación, personalización y análisis más efectivos de las campañas de marketing.
Por ejemplo, además de los datos comunes como nombre y correo electrónico, puedes agregar campos extras para almacenar información como edad, ubicación geográfica, preferencias de productos, historial de compras, entre otros.
La información del mensaje es:
Campo | Descripción | Obligatorio |
MessageTemplate | Nombre de la plantilla del mensaje | No existe plantilla si el canal es RCS |
MesssageParams |
Parámetros que forman parte de la personalización del mensaje. Nota: El número de parámetros debe ser la cantidad exacta de parámetros de la plantilla de mensaje seleccionada. Total de caracteres: 250 Listada en formato de array |
|
MessageContent | Campo que contiene el contenido del mensaje en caso de que sea el canal RCS | |
ChannelType | Es la definición del canal que se utilizará en el envío. Si no se especifica, se utilizará el canal de WhatsApp como predeterminado. | WhatsApp o GoogleRcs |
Campos de respuesta de la solicitud completados automáticamente
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 fallo en el envío. |
Campaña individual
Para enviar una campaña a solo un contacto, es necesario seguir el siguiente ejemplo, enviando como 'resource' un objeto que contenga las siguientes propiedades: campaign, audience y message.
Endpoint: /campaign/full
Solicitud para WhatsApp
{ |
Solicitud para Google RCS
{ |
Respuesta
{ |
En caso de que sea necesario tener información adicional en cada contacto, es posible agregar parámetros dentro del objeto audience en la propiedad messageParams, nombrados como por ejemplo 'extras1', 'extras2', y así sucesivamente. No es necesario que se definan como 'extra1' o 'extra2', lo importante es seguir el formato de 'clave' y 'valor'
De esta forma:
"audience": { |
Campaña masiva con envío único
Para enviar una campaña a varios contactos, el objeto resource debe contener las siguientes propiedades: campaign, audiences y message, siendo que el campo audiences debe ser del tipo array y la información definida en 'campaignType' debe ser 'Batch'.
Endpoint: /campaign/full
Solicitud para WhatsApp
{ |
Solicitud para Google RCS
{ |
Respuesta
{ |
Campaña masiva con audiencia dinámica (Beta)
Este enfoque implica el uso de múltiples 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, donde todo se hace en una única 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 granular sobre cada etapa del proceso de campaña.
Creación de la campaña
Endpoint: /campaign/v2
Solicitud para WhatsApp
{ |
Solicitud para Google RCS
{ |
Respuesta
{ |
Inclusión de audiencia
La inclusión de audiencia puede ser llamada tantas veces como sea necesario, limitada únicamente por la cantidad de audiencia permitida en la campaña.
Envío de lista en la solicitud
Endpoint: /audiences/v2/{{id da campanha criada}}
Solicitud
{ |
Respuesta
{ |
Envío de lista por archivo CSV
Endpoint: /audiences/v2/{{id de la campaña creada}}
Solicitud
{ |
Respuesta
{ |
Envío de la campaña
Se trata de la acción de enviar la campaña que ha sido creada y que tiene su audiencia completada.
Nota:
Una vez que la campaña ha sido enviada, ya no es posible incluir nuevas audiencias.
Endpoint: /dispatch/v2
Solicitud
{ |
Respuesta
{ |
Resumen de la campaña
A través de esta funcionalidad, tendrás acceso a información importante sobre tus campañas, lo que permite un análisis detallado del rendimiento y el estado del público objetivo.
Nota: Si no se especifica ningún filtro, se devolverán todas las campañas creadas en la fecha indicada o posterior.
La solicitud puede recibir los siguientes datos como filtro:
Campo | Descripción |
SourceApplication | Origen de la campaña, 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 esa fecha. |
En caso de no especificarse el filtro creado, se devolverán todas las campañas creadas en la fecha indicada o posterior.
La respuesta de la solicitud está compuesta por:
Campo | Descripción |
id | Identificador de la campaña |
messageTemplate | Identificador de la campaña |
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 e 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 cumplan con los criterios del filtro informado.
Endpoint: /campaigns/summaries
Solicitud
{ |
Respuesta
{ |
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 específica, como el template utilizado, la fecha de envío y el estado del público objetivo.
Endpoint: /campaigns/{Id da campanha}/summaries
Requisitos
- O ID da campanha
Solicitud
{ |
Respuesta
{ |
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 individuos, cuya selección puede basarse en criterios demográficos, comportamentales u otros factores relevantes.
Con nuestra API, puedes obtener información sobre la audiencia de una campaña.
Campos de la entidad de la 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 del modelo de mensaje. |
Campos de la respuesta
Campo | Descripción |
Total | Total de la audiencia |
Items | Lista especificando la audiencia |
Os itens são compostos por:
Campo | Descripción |
CampaignId | ID de la campaña |
Recipient | El destinatario del mensaje |
RecipientType | El tipo relacionado con lo que fue enviado en el destinatario (recipient), por ejemplo, si es un número de celular. |
ChannelType | El canal en el que se alcanzó al público |
MessageParams |
Parámetros que fueron enviados en el mensaje. El límite máximo de caracteres es de 250. |
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 el mensaje fue recibido. |
Read | La fecha y hora en que el mensaje fue leído. |
Failed | La fecha y hora en que el mensaje falló. |
ReasonCode | El código del motivo de fallo. |
ReasonDescription | La descripción del motivo de fallo. |
Obtener 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
- O ID da campanha.
Solicitud
{ |
Respuesta
{ |
Mensagem da campanha
Campos de la plantilla del mensaje
Campo | Descripción | Obligatorio |
ChannelType |
El tipo de canal. 'WhatsApp' = Predeterminado o 'GoogleRcs' |
|
MessageTemplate | El nombre de la plantilla del mensaje. | Usado con el canal WhatsApp |
MessageContent | El contenido del mensaje | Usado 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 del público objetivo cuando la campaña es individual. |
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 fueron enviados en el mensaje |
Obtener los mensajes de una campaña
Endpoint: /messages/{campaignId}
Requisitos
- El ID de la campaña
Solicitud
{ |
Respuesta
{ |
Para obtener un informe sobre el estado de una campaña, puede utilizar esta solicitud. El informe incluye información sobre la plantilla de mensaje utilizada en la campaña y el destino de redirección. Esto le permitirá tener una visión completa del rendimiento y los resultados de la campaña, ayudando a tomar decisiones para futuras optimizaciones.
Requisitos
- El 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 de 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 ha elegido esta opción. |
CampaignSender | Correo electrónico de quien envió la campaña. |
SendDate | Fecha en que la campaña fue enviada. |
StatusAudience | Una lista de los 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 de 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 de audiencia o en la solicitud al momento de la creación de la campaña. |
Status | El estado del público objetivo en el 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 el público objetivo fue enviado al usuario final. |
Received | La fecha y hora en que el público objetivo fue recibido por el usuario final. |
Read | La fecha y hora en que el público objetivo fue leído por el usuario final. |
Failed | La fecha y hora en que el público objetivo falló. |
NumberStatus | El estado de procesamiento del público objetivo. |
Obtener informe de una campaña específica
Endpoint: /campaigns/{campaignId}/reports
Solicitud
{ |
Respuesta
{ |
Preguntas frecuentes
¿Es posible hacer un envío por v2 con programación?
Sí, es posible. Solo necesitas especificar el campo ‘Scheduled’ en el formato ‘aaaa-MM-dd hh’ dentro de la entidad Campaña.
¿Es posible cancelar una campaña programada?
Puedes cancelar una campaña programada enviando un comando DELETE. Solo reemplaza {messageId} por el ID del mensaje de la campaña que deseas eliminar.
Cuerpo de la solicitud:
{ |
¿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 una vez que está programada. Para ello, es necesario eliminar la programación y crear una nueva campaña.
¿El envío de campañas en modo manual genera evidencia de que el mensaje fue enviado?
Para realizar el envío manual de mensajes activos, es posible agendar o enviar los disparos a través de Growth, y toda la información se registrará en la pantalla, ya sea sobre los mensajes que fallaron, que fueron recibidos o que fueron leídos.
Para más información, accede a la discusión sobre el tema en nuestra comunidad o a los videos en nuestro canal.😃