Skip to main content

[Alpha] How to configure the WhatsApp fallback API for Google RCS

  • Updated
  1. Summary
  2. Common data contract
  3. Integration steps
  4. Tips and validations

 

Summary

The fallback feature allows message delivery to be recovered in active campaigns. The process evaluates sending attempts from the primary channel and automatically copies eligible recipients whose deliveries failed to a secondary campaign on the destination channel. This guide is restricted to integrations where the primary channel is WhatsApp and the fallback channel is GoogleRCS.

Before you begin

  • Primary Channel: WHATSAPP.

  • Fallback Channel: GoogleRCS.

  • LIME Commands Endpoint: POST https://<owner-domain>/commands

  • Active Campaign Service Identity: postmaster@activecampaign.msging.net

  • Authentication: Header Authorization: Key <auth-key>

  • Unique Identifier: Every command sent must contain a unique id parameter.

  • Type Matching: The resource's type attribute in the request envelope must exactly match the type of resource being sent.

  • Sequential Evaluation: The fallback is evaluated after the primary campaign is dispatched; it is not executed as a second parallel campaign.

 

Common data contract

Campaign fallback

The fallback structure is declared within the campaign object:

{
  "fallback": {
    "channelType": "GoogleRCS",
    "message": {
      "channelType": "GoogleRCS",
      "messageContent": "Hello ${contact.extras.name}, your WhatsApp message was not delivered.",
      "messageParams": ["name"]
    }
  }
}

  • The fallback.message object is required whenever the fallback object is present in the request.

  • The fallback message must use the same channel configured in fallback.channelType.

  • While the primary message in a WhatsApp campaign uses an approved template, the fallback message is independent and must be created specifically for the Google RCS channel.

Field details:

  • fallback.channelType (Required): Must be set to "GoogleRCS".

  • fallback.message.channelType (Required): Must be exactly the same as fallback.channelType ("GoogleRCS").

  • fallback.message.messageContent (Required): Text/body of the message to be sent through the RCS channel.

  • fallback.message.messageParams (Optional): List containing the names of the dynamic parameters referenced in messageContent.

Dynamic parameters

Whenever the text in messageContent contains variables in the format ${contact.extras.<name>}, declare the corresponding names in the messageParams list:

{
  "messageContent": "Hello ${contact.extras.name}. Track it at ${contact.extras.url}.",
  "messageParams": ["name", "url"]
}

  • The audience record will provide the values used to populate the parameters declared in messageParams.

LIME command envelope

All calls use the LIME envelope structure below:

{
  "id": "<unique-command-id>",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "<resource-uri>",
  "type": "<resource-media-type>",
  "resource": {}
}

  • method: Use "set" to create, update, and dispatch resources. Use "get" to read resources and "delete" to remove them.

 

Integration steps

You can perform the integration through two operational flows: Incremental Flow (step-by-step) or Complete Flow (single operation).

Incremental Flow

Step 1: Create the campaign at /campaigns

Use this procedure to register the campaign and store the fallback configuration. This step does not create the messages or audience.

  • URI: /campaigns

  • Type: application/vnd.iris.activecampaign.campaign+json

Request:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c401",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaigns",
    "type": "application/vnd.iris.activecampaign.campaign+json",
    "resource": {
      "name": "WhatsApp campaign with RCS fallback",
      "channelType": "WHATSAPP",
      "campaignType": "INDIVIDUAL",
      "fallback": {
        "channelType": "GoogleRCS",
        "message": {
          "channelType": "GoogleRCS",
          "messageContent": "Hello ${contact.extras.name}, your WhatsApp message was not delivered.",
          "messageParams": ["name"]
        }
      }
    }
  }'

  • Important: Save the campaign id returned in the request response. It will be used in the following steps (/messages, /audiences, and /dispatch).

Step 2: Configure the primary message at /messages

Add the message template that will be used by the primary channel (WhatsApp).

  • URI: /messages/<campaign-id>

  • Type: application/vnd.iris.activecampaign.message+json

Request:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c402",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/messages/<campaign-id>",
    "type": "application/vnd.iris.activecampaign.message+json",
    "resource": {
      "channelType": "WHATSAPP",
      "messageTemplate": "order_delivered",
      "messageTemplateLanguage": "pt_BR"
    }
  }'

  • Attention: Do not send the fallback message in this call; the RCS channel message was already stored in the campaign registration (Step 1).

  • Queries: To query messages registered in a campaign, send a get command to the URI /messages/{campaignId} or /messages/{campaignId}/{channelType}.

Step 3: Add recipients at /audiences

Register the primary campaign audience. The channel specified in the audience records must correspond to the primary channel (WHATSAPP).

  • URI: /audiences/<campaign-id>

Option A: Single recipient

  • Type: application/vnd.iris.activecampaign.audience+json

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c403",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/audiences/<campaign-id>",
    "type": "application/vnd.iris.activecampaign.audience+json",
    "resource": {
      "recipient": "+5511999999999",
      "recipientType": "PhoneNumber",
      "channelType": "WHATSAPP",
      "messageParams": {
        "name": "Maria"
      }
    }
  }'
Option B: Multiple recipients (LIME collection)

  • Type: application/vnd.lime.collection+json

{
  "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c404",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/audiences/<campaign-id>",
  "type": "application/vnd.lime.collection+json",
  "resource": {
    "itemType": "application/vnd.iris.activecampaign.audience+json",
    "items": [
      {
        "recipient": "+5511999999999",
        "recipientType": "PhoneNumber",
        "channelType": "WHATSAPP",
        "messageParams": {
          "name": "Maria"
        }
      },
      {
        "recipient": "+5511888888888",
        "recipientType": "PhoneNumber",
        "channelType": "WHATSAPP",
        "messageParams": {
          "name": "João"
        }
      }
    ]
  }
}

  • Audience Rule: The fallback mechanism automatically remaps the eligible audience to the Google RCS channel. Do not manually create a second fallback audience.

Step 4: Execute the dispatch at /dispatch

Start sending the campaign. When fallback is configured, dispatch execution schedules the automatic failure check.

  • URI: /dispatch (or /dispatch/v2 for dynamic campaigns)

  • Type: application/vnd.iris.activecampaign.campaign+json

Request:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c405",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/dispatch",
    "type": "application/vnd.iris.activecampaign.campaign+json",
    "resource": {
      "id": "<campaign-id>"
    }
  }'

  • Additional Options: You can include the isToUseLiteApi, canSendWithOpenTicket, and usersFilter properties inside resource if required by your operation.

Complete Flow (Creation and dispatch in a single request)

Operation via /campaign/full

This endpoint creates the campaign, defines the primary message, registers the audience, and can dispatch the campaign simultaneously. It supports the INDIVIDUAL, GROUP, BATCH, USERSFILTER, and FROMCAMPAIGN campaign types.

  • URI: /campaign/full

  • Type: application/vnd.iris.activecampaign.full-campaign+json

Request:

curl --request POST \
  --url https://<owner-domain>/commands \
  --header 'Authorization: Key <auth-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c406",
    "to": "postmaster@activecampaign.msging.net",
    "method": "set",
    "uri": "/campaign/full",
    "type": "application/vnd.iris.activecampaign.full-campaign+json",
    "resource": {
      "campaign": {
        "name": "WhatsApp fallback to RCS",
        "channelType": "WHATSAPP",
        "campaignType": "INDIVIDUAL",
        "fallback": {
          "channelType": "GoogleRCS",
          "message": {
            "channelType": "GoogleRCS",
            "messageContent": "Hello ${contact.extras.name}, we are sending your message via RCS.",
            "messageParams": ["name"]
          }
        }
      },
      "message": {
        "channelType": "WHATSAPP",
        "messageTemplate": "order_delivered",
        "messageTemplateLanguage": "pt_BR"
      },
      "audiences": [
        {
          "recipient": "+5511999999999",
          "recipientType": "PhoneNumber",
          "channelType": "WHATSAPP",
          "messageParams": {
            "name": "Maria"
          }
        }
      ],
      "dispatch": true
    }
  }'

  • Set "dispatch": false if you want to create the complete structure without dispatching immediately.

Operation via /campaign/full/v2

Used for the dynamic flow of batch (BATCH) or user-filtered (USERSFILTER) campaigns.

  • URI: /campaign/full/v2

  • Type: application/vnd.iris.activecampaign.full-campaign+json

Example with BATCH sending:

{
  "id": "c2f2d9d0-2c8a-4f6a-bb58-0fcb1c17c407",
  "to": "postmaster@activecampaign.msging.net",
  "method": "set",
  "uri": "/campaign/full/v2",
  "type": "application/vnd.iris.activecampaign.full-campaign+json",
  "resource": {
    "campaign": {
      "name": "WhatsApp batch with RCS fallback",
      "channelType": "WHATSAPP",
      "campaignType": "BATCH",
      "fileUrl": "https://<media-host>/audience.csv",
      "fallback": {
        "channelType": "GoogleRCS",
        "message": {
          "channelType": "GoogleRCS",
          "messageContent": "Hello ${contact.extras.name}, your message is being resent via RCS.",
          "messageParams": ["name"]
        }
      }
    },
    "message": {
      "channelType": "WHATSAPP",
      "messageTemplate": "order_delivered",
      "messageTemplateLanguage": "pt_BR"
    },
    "dispatch": true
  }
}

  • For BATCH campaigns, the contact list is provided through the fileUrl field.

 

Tips and validations

Common errors and validation rules

The API will reject the request if any of the rules below is violated:

  1. The fallback object is present without the fallback.message property.

  2. A mismatch between fallback.message.channelType and fallback.channelType.

  3. The fallback channel is defined as identical to the campaign's primary channel.

  4. The value of fallback.channelType differs from GoogleRCS.

  5. The campaign's primary channel (campaign.channelType) differs from WHATSAPP.

  6. The primary message channel differs from campaign.channelType.

  7. Records in audiences are configured with a channel different from the primary channel.

  8. More than one fallback channel is configured in the same request.

Important: You must configure the fallback before dispatch. Sending fallback data after processing of the primary campaign has started is not supported and may cause inconsistencies.

Monitoring execution

  • The fallback campaign is automatically generated and dispatched by the service after the tolerance period for failures detected on the primary channel has ended.

  • Use query operations (get) on the campaign and audience endpoints to monitor both the execution of the primary campaign and the fallback campaign created by the system.

  • Do not manually create or manage the secondary fallback campaign.
     

 

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

Related articles