Guide BSG WhatsApp API Overview

This guide orients you to sending WhatsApp messages through the BSG API: how to authenticate, the send methods and what each is for, how a template request is built, and how to track delivery. It links out to the exact OneAPI methods for request/response detail — each method page has the full parameters and examples, and you can try calls in the Swagger explorer.

Quick start

Follow these in order for your first send:

1. Authenticate — exchange your API key for a bearer token.
2. Choose your send method — single, campaign, or universal.
3. Build the template request — name, language, and parameter values.
4. Track delivery — via callback or status lookup.

Also on this page: SMS fallback · Handling errors · Reading your account data.

Before you begin

You'll need:

• A connected WhatsApp Business Account (WABA) — if you haven't connected one yet, start with Getting started with 1-way WhatsApp on BSG.
• At least one approved template (created in Meta's WhatsApp Manager and synced into BSG).
• Your Live API key — from Management → Integrations & API → SMPP/API – password in the BSG cabinet.

Base URL: https://one-api.bsg.world

1. Authenticate

Exchange your API key for a bearer token (JWT), then send it as an Authorization: Bearer <JWT> header on every subsequent request. The token has a limited lifetime, so refresh it when needed. Your Live key sends real messages; the Test key returns sample data for building your integration (no real sends, no charges).

→ Receive JWT token · Refresh JWT token

2. Choose your send method

Three methods, depending on your use case — all send approved templates (type: template):

Pick single for transactional one-offs, campaign for bulk/scheduled sends, and universal if you're integrating WhatsApp as one channel in a multi-channel flow. Give each recipient a reference_id so you can match delivery updates later. A send returns status: accepted — final delivery arrives via callback or status lookup (Section 5).

3. Build the template request

A template send mirrors Meta's own structure — BSG passes your components through to Meta, so you build the same shape WhatsApp expects:

• name and language.code identify the approved template.
• components is an array of typed parts: body (your text parameters, in order), header (optional — text or media), and button (dynamic values for URL / quick-reply / copy-code buttons, addressed by sub_type and index).
• Parameter types include text, plus currency and date_time for localized values.
• You send only the parameter values; the template's fixed text, buttons, and structure come from the approved definition on Meta.

To find a template's name, language, and parameters, use Search WhatsApp templates and Get WhatsApp template. The exact components/parameters shape is documented on the send-method pages linked above.

Media headers: if a template has an image, video, or document header, supply the media at send time inside the header component — either a public HTTPS URL you host, or a BSG-supplied media id (never Meta's own media id). Keep within Meta's size limits (image 5 MB / video 16 MB / document 100 MB).

4. SMS fallback (optional)

If a WhatsApp message isn't delivered, BSG can automatically resend it as an SMS — useful for time-sensitive messages like OTPs. Add an alternative_channel.sms object (SMS text + sender, optional validity and stop-list check) to your send request; leave it out for a WhatsApp-only send. SMS is billed separately by BSG at its SMS rates. The exact fields are on the Send Single WhatsApp Message and Send WhatsApp campaign pages.

5. Track delivery

Via callback. Set a Callback URL For WhatsApp in Integrations & API (or a per-request callback_url on a single send). As each message progresses, BSG posts an update carrying the BSG message id, your reference, the current status, and — on failure — an error code. Single sends and campaigns use the same shape, and you get one update per status change (e.g. accepted → delivered). Inbound message/button forwarding will arrive on the same URL in a later release. For the exact payload and fields, see WhatsApp callbacks on BSG.

Status values: scheduled, moderation, accepted, sending, sent, delivered, read, expired, failed, undelivered, unknown.

Or pull status. Look a message up by your reference_id, by campaign_id (all messages in a campaign), or by BSG message id — see Get Single Message Info.

6. Handle errors

BSG mirrors Meta's error codes (pass-through, not reinterpreted). Quick triage: rejected means something on the request side needs attention (bad parameters, a limit, or billing — e.g. BSG code 99 = balance/plan limit); undeliverable means the request was fine but the message couldn't reach the recipient. HTTP 429 means too-frequent/duplicate requests — back off and retry. For the codes you're most likely to see and how to resolve them, see Common WhatsApp API errors.

7. Read your account data

Manage a campaign (list, details, calculate price, stop) via the universal Campaign methods. Note that pausing or stopping a campaign currently ends that run rather than resuming on its own; when you're ready to continue, launch a new campaign for the recipients you still want to reach.

Good to know

• Templates are managed on Meta. BSG syncs them read-only (~hourly); create and edit in WhatsApp Manager or via Meta's API.
• Throughput is high (order of ~1,000 messages/sec); Meta's portfolio-level limits also apply — see WhatsApp limits on BSG.
• SDKs are available for PHP, Node.js, Go, Python, Ruby, and Java — see the SDK documentation.

Next steps & related guides

• Getting started with 1-way WhatsApp on BSG — connect your WABA and configure your callback.
• WhatsApp callbacks on BSG — the delivery-status callback payload and fields.
• Common WhatsApp API errors — the most common sending errors and how to fix them.
• Connecting to BSG as a parallel second provider — validate BSG alongside your current provider.
• Full reference: BSG API documentation · Swagger explorer.