SMS Campaigns¶

SMS campaigns let teams send messages to many recipients instantly or at a scheduled time. A campaign can use the same content for everyone or personalize each message. Teams can preview the cost, track progress, pause or cancel sending, retry failures and receive eligible refunds.

Campaign options¶

Option	Choices	What it means
Content	`GENERIC`, `PERSONALIZED`	Send the same content to everyone or create different content for each recipient
Message type	`TRANSACTIONAL`, `PROMOTIONAL`	Send service messages or promotional messages
Sending time	`INSTANT`, `SCHEDULED`	Send as soon as the campaign is ready or at a chosen time
Recipients	Inline JSON, bulk CSV upload	Add up to 5,000 recipients directly or upload up to 1 million recipients by default

OTP is supported by direct messaging, not the campaign API.

Generic and personalized content¶

Generic campaigns¶

Every recipient receives the same text. Generic content cannot contain personalization placeholders.

Personalized campaigns¶

Personalized campaigns use placeholders such as {{name}}. Each recipient provides a value for every placeholder, and the platform inserts those values before calculating the message parts and cost.

For example, this template:

Hello {{name}}, your balance is BDT {{amount}}.

produces a different message for each recipient:

Recipient	`name`	`amount`	Final message
`8801712345678`	Rahim	500	`Hello Rahim, your balance is BDT 500.`
`8801812345678`	Karima	750	`Hello Karima, your balance is BDT 750.`

Rules include:

placeholder names begin with a letter and contain only letters, digits and underscores;
every required placeholder must be present, and unused extra values are rejected;
a value can contain at most 100 characters;
values cannot contain template braces or control characters;
final English (lang=en) messages must use supported GSM-7 characters;
each final message can contain at most ten SMS parts.

Personalized messages can therefore have different lengths, numbers of SMS parts and costs.

Adding recipients inline or by bulk CSV¶

Inline creation¶

Inline campaigns accept 1–5,000 recipient objects and complete validation, rendering, routing, pricing and one total balance deduction before returning 201.

Bulk CSV creation¶

CSV upload is currently promotional-only, requires Bangla (lang=bn), and accepts up to 1 million valid recipients and files up to 64 MB by default. The platform returns 202 BUILDING while it reads the file, checks the recipients and calculates the cost.

Generic CSV uses the first column as MSISDN and can include a header.
Personalized CSV requires an msisdn column plus one column for each template tag.
Invalid or duplicate rows are skipped and counted.
An invalid personalized CSV header causes the complete upload to fail.
All valid recipients are charged together as one campaign total.

Check the campaign until its status changes from BUILDING.

Previewing the cost¶

Preview checks an inline campaign and calculates its cost without creating the campaign or charging the balance. It shows the recipient count, SMS parts, total cost and encoding details.

The preview is an estimate because routes and rates can change before the campaign is created. After creation, each recipient's final content, rate, encoding, SMS parts and cost are saved. Operators can still switch an undispatched message to a configured fallback route.

Instant and scheduled sending¶

Promotional work must use Bangla and supply an operator-approved content/campaign ID.
Promotional dispatch must occur inside the configured BTRC window.
The current default window is 09:00 inclusive to 24:00 exclusive in Dhaka time; deployments can configure it.
If a promotional campaign is ready outside the allowed time, the platform waits until the next allowed sending time.

When the balance is charged¶

The platform calculates and charges the complete campaign cost before queueing it for sending:

recipient cost = (SMS parts × rate per part) + DI price
campaign cost  = total cost of all recipients

If campaign creation fails after the balance is charged, the platform returns the charge. Repeating this recovery process does not return the same charge twice.

Include an Idempotency-Key to prevent duplicate campaigns and charges when retrying inline or CSV creation. The key belongs to the signed-in username, remains valid for 24 hours and also covers the uploaded CSV content.

Campaign statuses¶

stateDiagram-v2
    [*] --> DRAFT: inline create
    [*] --> BUILDING: CSV accepted
    DRAFT --> QUEUED: instant charged
    DRAFT --> SCHEDULED: future charged
    BUILDING --> QUEUED: built and instant
    BUILDING --> SCHEDULED: built and scheduled
    DRAFT --> FAILED: create/charge failure
    BUILDING --> FAILED: build failure/stale
    SCHEDULED --> DISPATCHING: due
    QUEUED --> DISPATCHING: claimed
    SCHEDULED --> PAUSED: pause
    QUEUED --> PAUSED: pause
    DISPATCHING --> PAUSED: pause
    PAUSED --> SCHEDULED: resume scheduled
    PAUSED --> QUEUED: resume active
    DISPATCHING --> COMPLETED: all delivered
    DISPATCHING --> PARTIAL: mixed terminal results
    DISPATCHING --> FAILED: all failed
    SCHEDULED --> EXPIRED: deadline missed
    QUEUED --> CANCELLING: cancel
    SCHEDULED --> CANCELLING: cancel
    PAUSED --> CANCELLING: cancel
    CANCELLING --> CANCELLED: refund settled
    PARTIAL --> QUEUED: resend failures
    FAILED --> QUEUED: resend failures

Hold "Ctrl" to enable pan & zoom

DRAFT is a short preparation stage. BUILDING means a CSV is being processed. COMPLETED, PARTIAL, FAILED, CANCELLED and EXPIRED mean processing has ended, although failed or partially delivered campaigns can be reopened by resending failed recipients.

Managing a campaign¶

View progress¶

Clients can list their own campaigns by status, message type and creation date. Campaign details show cost and status totals, and clients can view each recipient's delivery, retry and refund result.

Pause and resume¶

Pausing stops new recipients from being sent. Messages already queued for provider delivery cannot be recalled, and pausing does not refund them. Resuming continues the campaign from its previous state.

Reschedule¶

Scheduled or paused campaigns can be given a new sending time. The new time is checked against the promotional sending window when applicable.

Cancel¶

Cancelling stops recipients that have not yet been sent and refunds their saved cost. Messages already queued for provider delivery may still finish.

Resend failed recipients¶

A PARTIAL or FAILED campaign can resend only the failed recipients. The platform calculates their latest price, charges them again and tracks the new attempt separately so earlier refunds do not affect it.

Retries, completion and refunds¶

A campaign can allow 0–10 retries with a delay of 0–1,440 minutes. Temporary failures such as timeouts, connection problems and selected provider errors can be retried. Only an actual attempt to send a message counts as a retry.

When every recipient has a final result, the campaign becomes COMPLETED, PARTIAL or FAILED. The platform calculates the cost of delivered messages and refunds eligible failures without refunding the same message twice.

Important limits¶

A successfully created campaign has been charged and queued or scheduled; its messages have not necessarily been delivered.
Pausing or cancelling cannot recall messages already queued for provider delivery.
Invalid or duplicate CSV rows are skipped, so the final recipient count may be lower than the number of uploaded rows.
Campaign status and reports can take time to update.
NOT_AVAILABLE and response code 9099 do not receive automatic refunds.

See the Campaign API and campaign process flows.