[Alpha] How to configure automatic SMS fallback via API (Fallback SMS) – Blip | Blip Help

Context

Automatic SMS fallback (also called fallback SMS) is a feature that acts as a secondary delivery channel for your active messages. If the message is not delivered through the original channel (WhatsApp or RCS) within a configured time window, the system automatically sends the content via SMS to the same contact, increasing the chances of delivery.

This guide shows how to configure and operate this feature directly through the Campaigns API (Active Campaign), covering the same behavior described in the article [Alpha] How to configure automatic SMS fallback in Blip Marketing, but for those who integrate directly with the API instead of using Blip Marketing.

Before you begin

Version: This feature is in the Alpha phase. To use it, contact your support team and request enablement.
Secondary channel: You must have the SMS channel contracted and configured in your Blip account.
Access permissions: Access to the Blip Marketing tab in Smart Contact.

The documentation below refers to use through the API. If you want to use this feature through the interface, access this documentation.

How it works

Configuring the fallback: when creating the campaign, you include the fallback object with the SMS channel and the text that will be sent during this retry.
Defining the SMS message: you write the fallback text manually, independently of the main channel message, while observing SMS character limits.
Monitoring delivery: after sending, the system checks whether the message was delivered through the main channel (WhatsApp or RCS) during the monitoring window.
Triggering the fallback: once this window has passed without delivery confirmation through the main channel, the system automatically creates and sends an SMS campaign only to recipients who failed.
Billing: each fallback SMS is charged according to the costs contracted for the SMS channel in your account; you only pay for SMS messages actually sent.

You do not need to call any endpoint to trigger the fallback: it occurs automatically and asynchronously after the main campaign is sent. If no recipient fails, no fallback SMS is sent and there is no additional charge.

Prerequisites and limitations

Fallback can only be configured for campaigns whose main channel is RCS (Google RCS) or WhatsApp. It is not possible to configure fallback for a campaign that is already SMS.
The only fallback channel currently supported is SMS.
Only one fallback can be configured per campaign (there is no chained fallback or multiple fallback channels in parallel).
There is no additional retry if the fallback SMS itself fails to send.
Fallback occurs only once per recipient.
The fallback text (message) is always required when you define the fallback channel. Sending the channel without the message results in a validation error.

Configuring automatic SMS fallback via API

Step 1 - Define the fallback when creating the campaign

Fallback is configured within the campaign creation payload itself (step-by-step flow SET /campaigns or combined flow SET /campaign/full / SET /campaign/full/v2), using the fallback field. Simply fill in the fallback object to enable it; there is no separate “on/off” flag.

Step 2 - Write the SMS message

The message sent as the fallback (fallback.message.messageContent) is independent of the main channel message. Write text adapted to the SMS context, keeping it concise and within the character limit (see SMS limitations and rules).

Example - RCS campaign configured with automatic SMS fallback

{
  "campaign": {
    "id": "campaign-rcs-001",
    "name": "RCS Campaign - Due date notice",
    "campaignType": "BATCH",
    "channelType": "GoogleRCS",
    "fallback": {
      "channelType": "SMS",
      "message": {
        "channelType": "SMS",
        "messageContent": "Hello {{0}}, your bill for {{1}} is due tomorrow. Avoid interest charges—pay on time."
        }
    }
  },
  "audiences": [
    {
      "recipient": "+5511999990000",
      "recipientType": "PHONENUMBER",
      "channelType": "GoogleRCS",
      "messageParams": { "nome": "Maria", "valor": "R$ 150,00" }
    }
  ],
  "message": {
    "channelType": "GoogleRCS",
    "messageContent": "Hello {{nome}}, your bill for {{valor}} is due tomorrow."
  },
  "dispatch": true
}

Fields of the fallback object

Field	Required	Description
channelType	Yes, to enable fallback	Channel used for the retry. Currently, only SMS is supported.
message	Yes, when channelType is provided	Message object (same format used in /messages) with the text that will be sent as the fallback.

If you send fallback.channelType without fallback.message, campaign creation is rejected with a validation error; the campaign is not created.

If you do not want to configure fallback, simply omit the fallback field (or send null).

Using variables in the SMS message

The fallback message also supports variables, allowing you to customize the content according to each recipient’s data.

Direct API integration (this guide): use {{0}} in messageContent, with the values sent in each audience item’s messageParams, using the same pattern as regular SMS messages (see How to send SMS messages through the Blip platform).
Campaigns created through Blip Marketing (portal): the variable syntax follows the pattern of the main channel configured for sending, as described in the Blip Help article. RCS uses ${contact.extras.nome}, and WhatsApp uses the template’s numeric position ({{0}}, {{1}}, ...). Using the wrong pattern causes the variable’s literal text to appear in the message sent to the contact, without substitution.

The character counter considers the variable itself (the placeholder text) as part of the text, not the final value that will be substituted for each contact. Leave a safety margin when creating the message, since longer values (compound names, for example) may exceed the limit even if the placeholder text is within it.

SMS limitations and rules

Character limit

160 characters for plain text (without accents, emojis, or special symbols).
70 characters for text containing accented characters, emojis, or special symbols.

This limit applies to the final message, with variables already replaced by each recipient’s actual value, not to the raw messageContent text before substitution.

Cost and billing

Automatic fallback is optional and subject to additional costs. Each fallback SMS is charged according to your SMS agreement, carrier fees, and the number of fallback messages sent.

Monitoring window

Fallback is triggered automatically after the configured monitoring period, without delivery confirmation through the main channel.
If the message is delivered before this period ends, the fallback SMS is not sent.
Fallback occurs only once per recipient.

Contact compatibility

Currently, WhatsApp-to-SMS fallback works exclusively for contacts identified by phone numbers. Sends that use identification through BSUID will not trigger automatic SMS fallback.

Sending the campaign

No changes are required when sending: use SET /dispatch (or dispatch: true in the combined flow) exactly as you would for a campaign without fallback configured. See the guide How to send SMS messages through the Blip platform for the sending format, which is the same regardless of the main channel.

Once the campaign is successfully sent, fallback monitoring starts automatically; you do not need to do anything else.

Viewing results

The original campaign’s CSV report includes two additional columns when fallback is configured:

Fell into fallback (Yes/No): indicates whether that recipient entered fallback (that is, failed on the original channel and was included in the automatically generated SMS campaign).
Fallback status: delivery status of the fallback message for that recipient (the same values used for normal delivery status), or - when not applicable.

GET /campaigns/{campaignId}/reports/csv

This is the same reporting endpoint already used for any campaign; no additional call is required to obtain fallback data:

If the campaign does not have fallback configured, the report is generated exactly as before, without the additional columns.
If the campaign has fallback configured but no fallback campaign has been created yet (for example, it is still within the monitoring window or no one has failed), all recipients appear with No and -.
If the fallback campaign has already been created, recipients who entered it appear with Yes and the current SMS delivery status.

Canceling the fallback

There is no specific endpoint to “cancel only the fallback.” When you delete the original campaign (DELETE /campaigns/{campaignId}), the system automatically:

Cancels scheduled monitoring if it has not yet been completed.
Removes the fallback message template associated with the campaign.

If the fallback campaign has already been created and sent before the original campaign is deleted, it is not affected; deletion only prevents new fallbacks from being created from that point onward.

Frequently asked questions (FAQ)

1. If I configure fallback, does it increase the cost of my campaign?

Yes. You only pay for SMS messages actually sent. If all contacts receive the message on WhatsApp/RCS within the monitoring window, no SMS is sent and there is no additional cost.

2. Can I use the same text as the main message for the fallback SMS?

It is not recommended. WhatsApp and RCS allow longer messages and formatting, while SMS is limited to 160 characters (or 70 with accented/special characters) and accepts only plain text. Adapt fallback.message.messageContent to the SMS context.

3. How do I know whether the fallback SMS was actually sent?

Check the campaign’s CSV report (GET /campaigns/{campaignId}/reports/csv): the Fell into fallback and Fallback status columns show, for each recipient, whether they entered fallback and the SMS delivery status.

4. Does automatic fallback work for individual and bulk campaigns?

Yes. The fallback field is accepted for any campaignType (INDIVIDUAL, BATCH, USERSFILTER, FROMCAMPAIGN), both in the step-by-step flow and in /campaign/full and /campaign/full/v2.

5. Can I schedule a campaign with automatic fallback configured?

Yes. Use the scheduled field normally when creating the campaign. Fallback continues to work as configured, applying the monitoring window from the actual send time (immediate or scheduled).

6. Do I need to call an endpoint to send the fallback?

No. The fallback SMS is sent automatically after the monitoring window has elapsed following the main campaign send.

7. Can I configure fallback for a campaign that is already SMS?

No. Fallback is intended to complement RCS or WhatsApp campaigns; the fallback campaign itself is already an SMS campaign.

8. What happens if several recipients fail at the same time?

They are all included in the same fallback campaign, created only once per source campaign (the system does not create a duplicate fallback campaign even if the check is triggered more than once).

9. Can I find out the ID of the generated fallback campaign?

No fallback ID is returned synchronously (creation is asynchronous). The way to track the result is through the original campaign’s CSV report, which already includes fallback status for each recipient.

10. Can I change the fallback text after the campaign has been created?

No. The fallback configuration is defined only when the campaign is created and cannot be edited later through the API.

11. If I delete the campaign before sending it, is the configured fallback canceled as well?

Yes. Deleting the campaign (DELETE /campaigns/{campaignId}) removes the fallback template and cancels any pending monitoring.

Best practices

What to do:

Keep the fallback message brief and direct (50–120 characters is a good guideline).
Validate the size of messageContent after replacing it with the values from messageParams, not just the text with placeholders.
Test with a small audience before configuring fallback for high-volume campaigns.
Monitor the Fell into fallback and Fallback status columns in the CSV report to measure fallback effectiveness in your campaigns.

What to avoid:

Using accents, emojis, or special symbols unnecessarily; they reduce the character limit from 160 to 70.
Sending fallback.channelType without fallback.message, as campaign creation will be rejected.
Blindly reusing the main message text (WhatsApp/RCS) as the SMS text without adapting it to the character limit.

Troubleshooting

Campaign creation fails with a fallback validation error

Likely cause: fallback.channelType was sent without fallback.message.
Solution: always send the complete message object within fallback when configuring the fallback channel.

The fallback SMS was not sent, even after the monitoring window

Likely cause: the recipient does not have a valid phone number, or no failure was recorded for that recipient on the main channel.
Solution: confirm that the audience’s recipient is a valid number and check the main channel delivery status in the report before expecting fallback.

The fallback columns do not appear in the CSV report

Likely cause: the campaign does not have fallback configured, or the monitoring window has not ended yet.
Solution: the columns only appear when fallback was defined during campaign creation. If the monitoring period has not yet passed, the values will appear as No/- until the fallback campaign is created.

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