Migrate your SMS traffic to BroadNet from any provider.

Map your current API onto BroadNet

Most SMS APIs share the same handful of concepts under different names. Find the concept in the first column, whatever your provider calls it, and use the BroadNet equivalent. Field names are exactly as they appear in the OpenAPI spec.

Here is the same send as a single request. Replace your provider's sender, recipient and text fields with senderId, destinationNumber and message:

curl -X POST https://api.broadnet.me/sms/sendSms \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "ACME",
    "destinationNumber": "447700900101",
    "message": "Your code is 8123",
    "messageType": "TEXT"
  }'

# 200 OK — the response body is the message ID, e.g. 2603121407537573731

To check one message, query its status with the message ID that the send request returned:

# Status lookup on the legacy HTTP API (/websmpp), by message ID
curl "https://api.broadnet.me/websmpp/websmsstatus?respid=2603121407537573731&format=json" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

# "status": "DELIVRD"   (or UNDELIV, EXPIRED, REJECTD)

Move your sender IDs

Alphanumeric sender IDs and short codes are generally portable, subject to each operator's and regulator's registration rules. A registration belongs to the route your traffic takes, so plan it before any production message moves to BroadNet.

1. 1

   List every sender ID, the countries it sends to and the type of traffic it carries: OTP, transactional or marketing.

2. 2

   Check each country's rules. In the UAE, sender IDs are registered under TDRA rules through the operator, one ID per legal entity per use case. In Saudi Arabia they need CST and operator approval, and foreign senders bind through a CST-licensed local aggregator.

3. 3

   Your migration engineer submits the registrations for BroadNet's routes, and BroadNet's compliance team follows each one through to approval.

4. 4

   Begin the parallel run in a country only after the sender ID is approved there for BroadNet's routes. Until then, keep sending through your current provider.

The rules for each market are on the regulations pages. SMS regulations by country

Run both providers in parallel

Keep your current provider live and add BroadNet as a second route behind a switch in your own code. Send first to your own verified numbers, then a small share of real traffic, and compare both routes on the same destinations.

Compare, per country and operator:

• The mix of delivery statuses: delivered, undelivered, expired and rejected.
• The time from sending a message to receiving its delivery receipt.
• The sender shown on the handset.
• The segment count for the same text, from POST /sms/identify.

Choose the route per recipient rather than per message, so that all OTP retries for one user go through the same provider. A minimal routing switch:

// Send a share of recipients through BroadNet; the rest stay on your
// current provider. BROADNET_SHARE is a percentage (0-100) you control.
const BROADNET_SHARE = Number(process.env.BROADNET_SHARE ?? "0");

// Same recipient -> same bucket, so OTP retries stay on one provider.
function bucket(to: string): number {
  let h = 0;
  for (const c of to) h = (h * 31 + c.charCodeAt(0)) >>> 0;
  return h % 100;
}

export async function sendSms(to: string, text: string, senderId: string) {
  if (bucket(to) < BROADNET_SHARE) return sendViaBroadNet(to, text, senderId);
  return sendViaCurrentProvider(to, text, senderId); // your existing code
}

async function sendViaBroadNet(to: string, text: string, senderId: string) {
  const res = await fetch("https://api.broadnet.me/sms/sendSms", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BROADNET_TOKEN}`,
      "Content-Type": "application/json",
    },
    // Use UNICODE for non-GSM text; POST /sms/identify tells you which.
    body: JSON.stringify({ senderId, destinationNumber: to, message: text, messageType: "TEXT" }),
  });
  if (!res.ok) throw new Error(`BroadNet send failed: ${res.status}`);
  return { provider: "broadnet", messageId: await res.text() };
}

Increase traffic in stages

Move production volume to BroadNet in steps you choose, one country or use case at a time. Stay at each step until its delivery receipts match what you sent, then take the next one.

1. Testing

   Your own verified numbers only. Confirm the sender ID, the message text and the delivery receipts.

2. 5%

   A small share of real traffic. OTP traffic to a single country returns fast, clear delivery receipts.

3. 25%

   Enough volume to compare delivery rates and receipt times with your current provider.

4. 100%

   All traffic for that country or use case. Your current provider stays live until the delivery receipts match what you sent.

How long it takes

Increasing traffic takes as long as you choose. Onboarding follows one path: we reply to a test-access request within one business day, technical integration takes 2–5 business days, and route validation with sender ID approval takes 3–10 business days. Most markets go from discovery to go-live in 5–15 business days; markets where regulators take longer to approve sender IDs take longer. See the onboarding steps

Roll back to your current provider without an outage

To roll back, use the same switch in reverse: lower the percentage of traffic sent through BroadNet to the last step that worked, or to zero. Your current integration and its sender ID registrations stay live the whole time, so lowering the percentage is enough. Nothing has to be rebuilt.

• Keep your current provider's credentials, sender ID registrations and webhook endpoint active until all traffic has moved and the delivery receipts match what you sent.
• Before you start, agree what triggers a rollback, for example a fall in the share of messages delivered in one country, and who is allowed to decide it.
• Keep your webhook handler running after a rollback: delivery receipts for messages already sent through BroadNet can still arrive.
• Retire the old route only after all traffic runs cleanly through BroadNet and the delivery receipts match what you sent.

Who is accountable for what

A migration touches your code, your sender registrations and live traffic. This is how the work is split.

Related documentation

Frequently asked questions