Guía de Migración: Plugin de la API de Broadcast de /messages → /campaign/full (API Active Campaign Growth) – Blip | Blip Help

Acerca de esta migración

Esta migración se aplica específicamente a las integraciones que utilizan el endpoint /messages para envío masivo de mensajes (Plugin de API de Broadcast).

Si utilizas otros recursos de la API /messages que no estén relacionados con el envío de campañas vía Broadcast, no es necesario realizar ningún cambio en este momento. Estos recursos continúan funcionando normalmente.

A lo largo de este artículo, presentamos las indicaciones para migrar únicamente el Plugin de la API de Broadcast (perteneciente a la API /messages) a la API de Growth, garantizando la continuidad de tus envíos y el acceso a las nuevas funcionalidades disponibles.

Estado actual - Broadcast

En la versión actual de la API de broadcast, existen 2 rutas principales para realizar los envíos

/api/v2/Broadcast/csv: A partir de un CSV enviado en el cuerpo de la solicitud es posible realizar los envíos
/api/v2/Broadcast/list: A partir de un body en JSON en el cuerpo de la solicitud es posible realizar los envíos

Además de las URIs, varios otros parámetros, vía encabezado y queryString, se utilizan en el envío

Headers

identifier: identificador del bot por el cual se enviarán las notificaciones
accessKey: la accessKey (TCP) del bot
organization: id de la organización para envío de las solicitudes a la plataforma
user: correo electrónico al que se enviará el reporte de los envíos

Querystring

phoneColumn: dado el payload, cuál será el campo (en el csv o en el json) que contendrá el teléfono para el envío
namespace: namespace al que está ligado el template a enviar
template: nombre del template a enviar
senderEmail: correo electrónico al que se enviará el reporte de los envíos
languageCode: idioma que será utilizado en el envío del template
scheduleTime: Dado el horario actual, cuántos segundos después queremos que la campaña sea programada (EJ: si queremos la campaña para 1h después del envío, debemos pasar 3600)

Cuerpo/CSV

Además de los parámetros mencionados arriba, algunos templates pueden necesitar variables adicionales. Estas variables se deciden de manera POSICIONAL, de modo que, si el Message Template contiene un video y 2 variables en el cuerpo de la solicitud, tendremos un cuerpo similar al ejemplo a continuación, donde la URL se pasará para el "HEADER" y las demás variables usadas en el cuerpo del mensaje

[
 {
 "telefone": "5531900000000",
 "url": "https://v.ftcdn.net/17/86/49/30/240_F_1786493040_OGqTFtyomFdsGwkoRbYkUSsWKINLbirM_ST.mp4",
 "var1": "ValorVar1",
 "var2: "ValorVar2",
 }
]

Ruta para migrar - Campaña Activa

En la versión actual de la API, se han puesto a disposición rutas de Active Campaign compatibles con los parámetros utilizados en las rutas de Broadcast

/api/v2/ActiveCampaign/list
/api/v2/ActiveCampaign/csv

Enviando una solicitud con el cuerpo mostrado en el ejemplo anterior, la campaña se creará normalmente

[
 {
 "telefone": "5531900000000",
 "url": "https://v.ftcdn.net/17/86/49/30/240_F_1786493040_OGqTFtyomFdsGwkoRbYkUSsWKINLbirM_ST.mp4",
 "var1": "ValorVar1",
 "var2: "ValorVar2",
 }
]

Visualización en la plataforma

Además de tener los envíos centralizados, en la pantalla de Growth/Mensajes Activos, las campañas se mostrarán con el prefijo WA-Broadcast-Plugin, indicando que provienen a través de la API, como muestra la imagen a continuación

Salud del número

A través de la misma pantalla también es posible validar la salud del número

De-Para de las requests

A continuación se presentan algunos comparativos, usando la sintaxis CURL como base, de cómo son las requests en modo broadcast y cómo pueden ser ajustadas para el modo Active Campaign.

Carrousel Templates

TLDR: Lo que cambia en resumen es únicamente el path de la solicitud

Broadcast: /api/v2/Broadcast/csv y /api/v2/Broadcast/list
Active Campaign: /api/v2/ActiveCampaign/csv y /api/v2/ActiveCampaign/list

Tipo Carrousel

La API de broadcast no soporta el envío tipo Carrousel por ella. Para enviar Campañas Activas de este tipo, utiliza directamente la aplicación de Campaña Activa

CSV

Texto Simple

Broadcast

curl --location 'https://takebroadcast.cs.blip.ai/api/v2/Broadcast/csv?phoneColumn=telefone&namespace=<NAMESPACE_TEMPLATE_WPP>&template=<TEMPLATE_TEXTO_SIMPLES>&senderEmail=<EMAIL_PARA_NOTIFICACAO>&languageCode=<IDIOMA_TEMPLATE_PARA_ENVIO>&scheduleTime=0&headerVariables=true&separator=%2C' \
--header 'identifier: <ID_DO_BOT>' \
--header 'accessKey: <ACCESS_KEY_BOT>' \
--header 'organization: <ID_ORGANIZACAO>' \
--header 'user: <EMAIL_PARA_NOTIFICACAO>' \
--form 'formFile=@"/<DIRETORIO_ARQUIVO_CSV>/csv-without-variable.csv"'
- ActiveCampaign
curl --location 'https://takebroadcast.cs.blip.ai/api/v2/ActiveCampaign/csv?phoneColumn=telefone&namespace=<NAMESPACE_TEMPLATE_WPP>&template=<TEMPLATE_TEXTO_SIMPLES>&senderEmail=<EMAIL_PARA_NOTIFICACAO>&languageCode=<IDIOMA_TEMPLATE_PARA_ENVIO>&scheduleTime=0&headerVariables=true&separator=%2C' \
--header 'identifier: <ID_DO_BOT>' \
--header 'accessKey: <ACCESS_KEY_BOT>' \
--header 'organization: <ID_ORGANIZACAO>' \
--header 'user: <EMAIL_PARA_NOTIFICACAO>' \
--form 'formFile=@"/<DIRETORIO_ARQUIVO_CSV>/csv-without-variable.csv"'

Ruta de /Notifications

Esta ruta existe desde las primeras versiones de la API y su propósito es permitir el envío de notificaciones individuales a los usuarios. En la ruta de ActiveCampaign, utilizando el endpoint de /list, podemos enviar una Campaña de un usuario para mantener la compatibilidad con el uso actual.

Diferencias principales

Para realizar la conversión de las rutas, existen algunas diferencias en cómo se utilizan los parámetros

Querystrings y Headers

Los parámetros namespace, template y languageCode no se envían en el cuerpo de la solicitud sino como querystring;
Es necesario utilizar el parámetro phoneColumn=telefone para indicar cuál es el campo que contendrá el número que recibirá el mensaje activo;
Es necesario agregar el encabezado senderEmail
Es necesario agregar el campo scheduleTime para permitir la programación del envío
Los parámetros identifier, accessKey, organization y user mantienen el mismo comportamiento, sin necesidad de cambios.

Cuerpo de la solicitud

En el cuerpo de la solicitud, el campo que contendrá el teléfono al que se enviará la notificación debe coincidir con lo especificado en el parámetro phoneColumn (en el ejemplo del artículo, el cuerpo debe contener el body telefone)

Los demás campos son posicionales:

Si un template es del tipo imagen: el primer parámetro del body será la URL del medio a enviar y los demás serán referentes al texto de la leyenda del mensaje
Si un template es del tipo video: el primer parámetro del body será la URL del medio a enviar y los demás serán referentes al texto de la leyenda del mensaje
Notification

curl --location 'https://takebroadcast.cs.blip.ai/api/v2/Notification/' \
--header 'Content-Type: application/json' \
--header 'identifier: <BOT_ID>' \
--header 'accessKey: <BOT_ACCESS_KEY>' \
--header 'organization: <ORGANIZATION_ID>' \
--header 'user: <USER_EMAIL>' \
--header 'costCentre: 0' \
--data '{
 "phoneNumber": "<PHONENUMBER>",
 "namespace": "<MESSAGE_TEMPLATE_NAMESPACE>",
 "template": "<MESSAGE_TEMPLATE>",
 "languageCode": "<MESSAGE_TEMPLATE_LANGUAGE>",
 "parameters": {
 "header": {
 "type": "image",
 "url": "https://images3.alphacoders.com/107/thumb-1920-1070509.jpg"
 },
 "body": [
 "<VARIABLE_VALUE>"
 ]
 }
}'

Ruta de campaña activa

curl --location 'https://takebroadcast.cs.blip.ai/api/v2/ActiveCampaign/list?phoneColumn=telefone&namespace=<MESSAGE_TEMPLATE_NAMESPACE>&template=<MESSAGE_TEMPLATE>&senderEmail=tulior%40blip.ai&languageCode=<MESSAGE_TEMPLATE_LANGUAGE>&scheduleTime=0' \
--header 'Content-Type: application/json' \
--header 'identifier: <BOT_ID>' \
--header 'accessKey: <BOT_ACCESS_KEY>' \
--header 'organization: <ORGANIZATION_ID>' \
--header 'user: <USER_EMAIL>' \
--header 'costCentre: 0' \
--data '[
 {
 "telefone": "<PHONENUMBER>",
 "url": "https://images3.alphacoders.com/107/thumb-1920-1070509.jpg",
 "var1": "<VARIABLE_VALUE>"
 }
]'

Envío Directo

Consulta el artículo en el que enseñamos a utilizar directamente la aplicación de Active Campaign, con las URLs de la plataforma: Cómo enviar notificaciones vía API Active Campaign (Growth)

¿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 😃