Skip to main content

Migration Guide: Broadcast API Plugin from /messages → /campaign/full (API Active Campaign Growth)

  • Updated
  1. About this migration
  2. Current status - Broadcast
  3. Route to migrate - Active Campaign
  4. Request mapping
  5. Route for /Notifications
  6. Direct Sending

 

About this migration

This migration specifically applies to integrations that use the /messages endpoint for mass messaging (Broadcast API Plugin).

If you use other /messages API features not related to sending campaigns via Broadcast, no changes are necessary at this time. Those features will continue to work normally.

Throughout this article, we provide guidelines to migrate only the Broadcast API Plugin (part of the /messages API) to the Growth API, ensuring continuity of your sends and access to new available features.

 

Current status - Broadcast

In the current version of the broadcast API, there are 2 main routes to perform sends

  • /api/v2/Broadcast/csv: It is possible to send messages using a CSV sent in the request body

  • /api/v2/Broadcast/list: It is possible to send messages using a JSON body in the request

Besides the URIs, several other parameters via headers and queryString are used in the sending process

Headers

  • identifier: identifier of the bot from which the notifications will be sent

  • accessKey: the bot's accessKey (TCP)

  • organization: organization ID for sending requests to the platform

  • user: email to which the send report will be sent

Querystring

  • phoneColumn: given the payload, which field (in the CSV or JSON) contains the phone number to send to

  • namespace: namespace to which the template to be sent is linked

  • template: name of the template to be sent

  • senderEmail: email to which the send report will be sent

  • languageCode: language that will be used for sending the template

  • scheduleTime: Given the current time, how many seconds later we want the campaign to be scheduled (EX: if we want the campaign for 1 hour after sending, we need to pass 3600)

Body/CSV

In addition to the parameters mentioned above, some templates may require additional variables. These variables are decided POSITIONALLY, so if the Message Template contains a video and 2 variables in the request body, we will have a body similar to the example below, where the URL will be passed to the "HEADER" and the other variables used in the message body

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

 

Route to migrate - Active Campaign

In the current version of the API, Active Campaign routes compatible with the parameters used in Broadcast routes have been made available

  • /api/v2/ActiveCampaign/list

  • /api/v2/ActiveCampaign/csv

Sending a request with the body shown in the previous example will create the campaign normally

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

Platform view

Besides having centralized sends, on the Growth/Active Messages screen, campaigns will be displayed with the prefix WA-Broadcast-Plugin, indicating they came through the API, as shown in the image below

Number health

Through the same screen, it is also possible to validate the health of the number

 

Request mapping

Below are some comparisons, using CURL syntax as a base, of how requests are in broadcast mode and how they can be adjusted for Active Campaign mode.

Carousel Templates

TLDR: The only change in summary is the request path

  • Broadcast: /api/v2/Broadcast/csv and /api/v2/Broadcast/list

  • Active Campaign: /api/v2/ActiveCampaign/csv and /api/v2/ActiveCampaign/list

Carousel type

The Broadcast API does not support sending Carousel type messages. To send Active Campaigns of this type, use the Active Campaign application directly.

CSV

Simple Text

  • Broadcast

curl --location 'https://takebroadcast.cs.blip.ai/api/v2/Broadcast/csv?phoneColumn=telefone&namespace=<NAMESPACE_TEMPLATE_WPP>&template=<TEMPLATE_SIMPLE_TEXT>&senderEmail=<EMAIL_FOR_NOTIFICATION>&languageCode=<TEMPLATE_LANGUAGE_FOR_SENDING>&scheduleTime=0&headerVariables=true&separator=%2C' \
--header 'identifier: <BOT_ID>' \
--header 'accessKey: <BOT_ACCESS_KEY>' \
--header 'organization: <ORGANIZATION_ID>' \
--header 'user: <EMAIL_FOR_NOTIFICATION>' \
--form 'formFile=@"/<CSV_FILE_DIRECTORY>/csv-without-variable.csv"'
- ActiveCampaign
curl --location 'https://takebroadcast.cs.blip.ai/api/v2/ActiveCampaign/csv?phoneColumn=telefone&namespace=<NAMESPACE_TEMPLATE_WPP>&template=<TEMPLATE_SIMPLE_TEXT>&senderEmail=<EMAIL_FOR_NOTIFICATION>&languageCode=<TEMPLATE_LANGUAGE_FOR_SENDING>&scheduleTime=0&headerVariables=true&separator=%2C' \
--header 'identifier: <BOT_ID>' \
--header 'accessKey: <BOT_ACCESS_KEY>' \
--header 'organization: <ORGANIZATION_ID>' \
--header 'user: <EMAIL_FOR_NOTIFICATION>' \
--form 'formFile=@"/<CSV_FILE_DIRECTORY>/csv-without-variable.csv"'

 

Route for /Notifications

This route has existed since the first versions of the API and its purpose is to allow sending individual notifications to users. In the ActiveCampaign route, using the /list endpoint, we can send a user campaign to maintain compatibility with current usage.

Main differences

To convert the routes, there are some differences in how parameters are used

Querystrings and Headers

  • The parameters namespace, template, and languageCode are not sent in the request body but as querystrings;

  • It is necessary to use the parameter phoneColumn=telefone to indicate which field will contain the number to receive the active message;

  • It is necessary to add the senderEmail header

  • It is necessary to add the scheduleTime field to allow scheduling the send

  • The parameters identifier, accessKey, organization, and user remain with the same behavior, requiring no changes.

Request body

In the request body, the field containing the phone number to which the notification will be sent must match what is specified in the phoneColumn parameter (in the article example, the body must contain the field telefone)

The other fields are positional:

  • If a template is of image type: the first parameter in the body will refer to the media URL to be sent and the others to the message caption text

  • If a template is of video type: the first parameter in the body will refer to the media URL to be sent and the others to the message caption text

     

  • 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>"
 ]
 }
}'

  • Active campaign route

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>"
 }
]'

 

Direct Sending

Check out the article where we teach how to use the Active Campaign application directly, with platform URLs: How to send notifications via Active Campaign API (Growth)


 

Need more help? Explore our content at Blip Academy or Blip Community, watch tutorials on our YouTube channel or get your questions answered in our support channel 😃

Related articles