Skip to main content

How to Trigger Active Message via API through the SMS Channel

  • Updated
  1. Objective
  2. Flow Overview
  3. Create the Campaign — SET /campaigns
  4. Register the Audience — SET /audiences/{campaignId}
  5. Set the Message — SET /messages/{campaignId}
  6. Dispatch the Campaign — SET /dispatch
  7. Combined Flow — SET /campaign/full
  8. Dynamic Combined Flow — SET /campaign/full/v2
  9. Important Rules for the SMS Channel

 

Objective

This article shows how to use the Campaigns API (Active Campaign) to create, configure, and trigger an active message campaign through the SMS channel. It covers the step-by-step flow (/campaigns, /audiences, /messages, /dispatch) and the combined flows (/campaign/full and /campaign/full/v2), which do everything in a single call.

Prerequisites

  • The SMS channel needs to be enabled for your account/environment. If it is not enabled, any request with channelType = SMS will be rejected with a validation error.

  • Requests are sent as commands using the LIME protocol (Set/Get), authenticated with the bot's identity.

 

Flow Overview

There are two ways to trigger an SMS campaign:

  1. Step-by-step flow — four separate calls: create campaign, register audience, set the message, and dispatch. Provides more control over each step before sending.

  2. Combined flow — a single call that creates the campaign, registers the audience, sets the message, and dispatches. Use /campaign/full for most cases, or /campaign/full/v2 for large databases (via file) or user filters.

 

Create the Campaign — SET /campaigns

Creates the campaign record, setting the channel as SMS.

Content type (mime type): application/vnd.iris.activecampaign.campaign+json

Request Example

{
  "id": "campaign-sms-001",
  "name": "SMS Campaign - Payment Reminder",
  "campaignType": "INDIVIDUAL",
  "channelType": "SMS"
}

Fields

Field Required Description
id Yes Unique identifier of the campaign, defined by you.
name Yes Descriptive name of the campaign.
campaignType Yes INDIVIDUAL (one recipient), BATCH (multiple recipients).
channelType Yes Use SMS.
fileUrl No URL of a CSV file with the list of recipients, used when campaignType = BATCH.
scheduled No Date/time to schedule the sending. If omitted, the campaign is treated as immediate.
notificationEmail / notificationEmailLanguage No Email (and language) to receive notification if the campaign fails.
tags No List of tags to group and filter campaigns in reports.

If the SMS channel is not enabled in your environment, this call returns a validation error and the campaign is not created.

 

Register the Audience — SET /audiences/{campaignId}

Adds the recipients who will receive the SMS message.

Content type: application/vnd.iris.activecampaign.audience+json

Request Example (list of recipients)

[
  {
    "recipient": "+5511999990000",
    "recipientType": "PHONENUMBER",
    "channelType": "SMS",
    "messageParams": {
      "nome": "Maria",
      "valor": "R$ 150,00"
    }
  },
  {
    "recipient": "+5511988880000",
    "recipientType": "PHONENUMBER",
    "channelType": "SMS",
    "messageParams": {
      "nome": "João",
      "valor": "R$ 90,00"
    }
  }
]

Fields

Field Required Description
recipient Yes Phone number in international format, with + (e.g., +5511999990000).
recipientType No (default is PHONENUMBER) Type of recipient.
channelType Yes Use SMS, same as defined in the campaign.
messageParams No Variables used to personalize the message text (e.g., {{nome}}, {{valor}}).
contextVariables No Additional context variables, not used in the message text.

If you already provided fileUrl in the campaign (campaignType = BATCH), you do not need to call /audiences manually — recipients are loaded automatically from the file.

 

Set the Message — SET /messages/{campaignId}

Defines the text that will be sent via SMS.

Content type: application/vnd.iris.activecampaign.message+json

Request Example

{
  "channelType": "SMS",
  "messageContent": "Hello {{0}}, your bill of {{1}} is due tomorrow. Avoid fees, pay on time.",
  "messageParams": ["nome", "valor"]
}

Fields

Field Required Description
channelType Yes Use SMS.
messageContent Yes Message text. Use {{0}} to insert the values defined in messageParams for each recipient.
messageParams No List of parameter names expected in the text (reference/documentation).
messageTemplate / messageTemplateLanguage Not applicable to SMS Used only in WhatsApp campaigns; for SMS, these fields are ignored.

Tip: avoid accents and special characters in the message text. They can increase the number of parts into which the SMS is split by the carrier, raising the cost of sending.

 

Dispatch the Campaign — SET /dispatch

Starts the actual sending of the messages of the already created campaign.

Content type: application/vnd.iris.activecampaign.campaign+json (only the fields below are considered)

Request Example

{
  "id": "campaign-sms-001",
  "isToUseLiteApi": false,
  "canSendWithOpenTicket": false
}

Fields

Field Required Description
id Yes Campaign ID created in step 1.
isToUseLiteApi No Indicates if the dispatch should use the Lite API.
canSendWithOpenTicket No Allows sending even if the contact has an open support ticket.

After dispatch, sending is processed asynchronously: each recipient goes through account validation, registration, and message sending, with status updates according to delivery results.

 

Combined Flow — SET /campaign/full

Creates the campaign, registers the audience(s), sets the message, and dispatches everything in a single call. Use for campaigns of type INDIVIDUAL, BATCH.

Content type: application/vnd.iris.activecampaign.full-campaign+json

Request Example (campaign for a group of recipients via SMS)

{
  "campaign": {
    "id": "campaign-sms-full-001",
    "name": "SMS Full Campaign - Promotion",
    "campaignType": "GROUP",
    "channelType": "SMS"
  },
  "audiences": [
    {
      "recipient": "+5511999990000",
      "recipientType": "PHONENUMBER",
      "channelType": "SMS",
      "messageParams": { "nome": "Maria" }
    },
    {
      "recipient": "+5511988880000",
      "recipientType": "PHONENUMBER",
      "channelType": "SMS",
      "messageParams": { "nome": "João" }
    }
  ],
  "message": {
    "channelType": "SMS",
    "messageContent": "Hello {{0}}, enjoy our promotion until tomorrow!",
"messageParams": ["nome"]
  },
  "dispatch": true
}

Fields

Field Required Description
campaign Yes Campaign data (same fields as in step 1).
audience Conditional Used for a single recipient (campaignType = INDIVIDUAL).
audiences Conditional List of recipients (campaignType = BATCH).
message Yes SMS message text (same fields as in step 3).
dispatch No (default is true) If false, creates the campaign without automatically dispatching.

 

Dynamic Combined Flow — SET /campaign/full/v2

Variant of the combined flow aimed at large databases: BATCH campaigns (source via CSV file). It is the recommended option for high volumes of recipients, as it processes the source asynchronously.

Content type: application/vnd.iris.activecampaign.full-campaign+json (same format as /campaign/full)

Only campaignType = BATCH or USERSFILTER are accepted on this endpoint. Any other value is rejected.

Request Example (batch SMS campaign, source by file)

{
  "campaign": {
    "id": "campaign-sms-full-v2-001",
    "name": "SMS Full Campaign V2 - Complete Database",
    "campaignType": "BATCH",
    "channelType": "SMS",
    "fileUrl": "https://storage.example.com/audiencias-sms.csv"
  },
  "message": {
    "channelType": "SMS",
    "messageContent": "Hello {{0}}, your invoice is available.",
"messageParams": ["nome"]
  },
  "dispatch": true
}

 

Important Rules for the SMS Channel

  • Coexistence with other channels: enabling SMS does not affect the operation of existing campaigns in WhatsApp or Google RCS.

 

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 😃