Kirim SMS via API: Contoh Python, Node.js, PHP, dan cURL

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

// Node.js 18+ (fetch bawaan)
const res = await fetch("https://api.broadnet.me/sms/sendSms", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BROADNET_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    senderId: "OmniDemo",
    destinationNumber: "447700900123",
    message: "Your OmniDemo code is 482913",
    messageType: "TEXT",
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const messageId = await res.text(); // ID pesan berupa teks biasa

import os
import requests

r = requests.post(
    "https://api.broadnet.me/sms/sendSms",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    json={
        "senderId": "OmniDemo",
        "destinationNumber": "447700900123",
        "message": "Your OmniDemo code is 482913",
        "messageType": "TEXT",
    },
    timeout=15,
)
r.raise_for_status()
message_id = r.text  # ID pesan berupa teks biasa, bukan JSON

<?php
$payload = json_encode([
    "senderId" => "OmniDemo",
    "destinationNumber" => "447700900123",
    "message" => "Your OmniDemo code is 482913",
    "messageType" => "TEXT",
]);

$ch = curl_init("https://api.broadnet.me/sms/sendSms");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BROADNET_TOKEN"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => $payload,
]);
$messageId = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
echo $status . " " . $messageId . PHP_EOL;

2603121407537573731

r = requests.post(
    "https://api.broadnet.me/sms/sendSms",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    json={
        "senderId": "OmniDemo",
        "destinationNumber": "971500000000",
        "message": "رمز التحقق الخاص بك هو 482913",
        "messageType": "UNICODE",
        "campaignName": "login-otp",
    },
    timeout=15,
)

Bagaimana menghitung segmen sebelum mengirim?

Panggil POST /sms/identify dengan pesan Anda. Endpoint ini mengembalikan encoding yang terdeteksi, jumlah karakter, jumlah segmen, dan batas per segmen.

curl -X POST https://api.broadnet.me/sms/identify \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Your OmniDemo code is 482913" }'

{
  "message": "Your OmniDemo code is 482913",
  "messageType": "TEXT",
  "smscount": 1,
  "charCount": 28,
  "charLimit": 160
}

Anda dapat meneruskan smsParts (dari smscount), charCount, dan charLimit ke request pengiriman. Teks GSM-7 mungkin diberi label GSM-7 dalam respons; kirim sebagai TEXT.

Bagaimana mengirim ke banyak nomor?

Gunakan POST /sms/sendbulk, request multipart/form-data dengan file penerima dan string JSON berisi pengaturan.

curl -X POST https://api.broadnet.me/sms/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F destinationNumberFile=@recipients.csv \
  -F 'bulkRequest={"senderId":"OmniDemo","message":"Your statement is ready in the app.","messageType":"TEXT","campaignName":"oct-statements","allowDuplicate":false}'

import json
import os
import requests

bulk_request = {
    "senderId": "OmniDemo",
    "message": "Your statement is ready in the app.",
    "messageType": "TEXT",
    "campaignName": "oct-statements",
    "allowDuplicate": False,
}

with open("recipients.csv", "rb") as f:
    r = requests.post(
        "https://api.broadnet.me/sms/sendbulk",
        headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
        files={"destinationNumberFile": ("recipients.csv", f, "text/csv")},
        data={"bulkRequest": json.dumps(bulk_request)},
        timeout=60,
    )
print(r.json())

Respons memuat bulkSessionId dan objek bulkListInfo dengan total, validCount, invalidCount, dan duplicate. Simpan bulkSessionId bersama kampanye. Job dapat didaftar, dijeda, dilanjutkan, dan dibatalkan dengan endpoint dalam referensi. Anda juga dapat memeriksa nomor sebelum pengiriman besar dengan POST /sms/lookup; lihat panduan HLR lookup kami.

Bagaimana menerima status pengiriman?

Status pengiriman dikirim (push) ke URL webhook yang dikonfigurasi di akun Anda. Sebuah pesan bergerak melalui SUBMITTED dan SENT menuju DELIVERED, atau berakhir sebagai FAILED atau REJECTED. Anda memberikan URL HTTPS publik kepada tim kami, dan reseller dapat memiliki satu webhook per sub-akun.

Field payload bervariasi menurut kanal, dan spesifikasi API tidak mendefinisikan satu skema webhook tunggal, jadi catat body mentah terlebih dahulu dan petakan field dari event nyata di akun Anda. Penerima minimal menyimpan event dan menjawab dengan cepat:

import express from "express";

const app = express();

app.post("/webhooks/omnichannels", express.json(), async (req, res) => {
  await saveStatusEvent(req.body); // penyimpanan Anda; proses secara asinkron
  res.sendStatus(200);             // jawab dengan cepat
});

app.listen(3000);

Buat pemrosesan idempoten, karena status yang sama bisa tiba dua kali, dan jangan biarkan SENT yang terlambat menimpa DELIVERED yang sudah tersimpan. Jika endpoint Anda sempat mati, POST /sms/resendDlr mengirim ulang laporan untuk rentang tanggal:

curl -X POST https://api.broadnet.me/sms/resendDlr \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-10-09",
    "endDate": "2026-10-10",
    "senderId": "OmniDemo",
    "messageStatus": "DELIVERED"
  }'

Baca selengkapnya di panduan webhook dan di status pengiriman pesan dijelaskan.

Bagaimana menangani error dan menghindari duplikasi?

Tangani status HTTP terlebih dahulu, lalu body error. Ulangi hanya untuk error jaringan, 429, dan 5xx.

Error yang dimunculkan API memakai body JSON lima field dengan status, error, message, errorCode, dan requestUri. Batas REST yang terdokumentasi secara default adalah 200 request per detik secara berkelanjutan; batas akun Anda dikonfirmasi bersama kredensial Anda.

API tidak menerima idempotency key. Sebuah request bisa berhasil sementara responsnya hilang, dan pengulangan buta kemudian mengirim dua kali. Tulis baris pending dengan kunci ID operasi Anda sendiri sebelum memanggil, simpan ID pesan yang dikembalikan, dan setelah timeout periksa status webhook sebelum mengirim lagi. Untuk pengiriman massal, atur allowDuplicate ke false. Rinciannya ada di Error dan batas.

Contoh kasus: kode login untuk aplikasi regional

"Souq Rafiq" (fiktif), pengecer di UEA, mengirim kode login lewat SMS.

1. Layanan autentikasi membuat kode enam digit, menyimpan hash dengan masa berlaku lima menit, dan menulis baris pengiriman pending.
2. Layanan memanggil /sms/sendSms dengan messageType=UNICODE untuk pengguna Arab dan TEXT untuk pengguna Inggris.
3. Pada 200, layanan menyimpan ID pesan.
4. Handler webhook menandai baris sebagai DELIVERED, FAILED, atau REJECTED.
5. Jika statusnya bukan DELIVERED setelah jeda singkat, aplikasi menawarkan kirim ulang dan, jika dikonfigurasi, kanal lain. Lihat fallback kanal.
6. Batas laju pada permintaan kode per nomor dan per IP melindungi dari penyalahgunaan; lihat pencegahan SMS pumping.

Apa saja kesalahan umum?

• Memanggil r.json() pada respons pengiriman. Responsnya teks biasa.
• Nama field yang salah. Gunakan senderId, destinationNumber, dan message; field seperti to, from, atau text bukan bagian dari endpoint ini.
• Tanda plus dan nol di depan pada nomor.
• Lupa UNICODE untuk bahasa Arab, yang membuat teks menjadi acak.
• Sender ID yang tidak terdaftar. Beberapa negara memblokir atau menggantinya; periksa aturan Sender ID untuk tujuan Anda, dan minta kami menangani registrasinya.
• Menganggap 200 sebagai terkirim.
• Token di aplikasi seluler atau browser, tempat siapa pun dapat mengambilnya.
• Batasan: panduan ini menunjukkan request yang umum. Field opsional seperti format penjadwalan sebaiknya dikonfirmasi dengan tim kami.

Bagaimana OmniChannels.ai membantu

OmniChannels.ai mengirim A2P SMS melalui konektivitas operator langsung milik BroadNet, dengan SMS dua arah, Sender ID, Unicode dan Arab, HLR lookup, dan SMPP 3.4 untuk volume tinggi. REST API di https://api.broadnet.me memakai Bearer token dan juga mencakup WhatsApp, RCS, dan kanal lain, dengan status pengiriman yang dinormalisasi ke satu format webhook. Tim kami menyiapkan registrasi Sender ID bersama Anda. Lihat referensi SMS API atau kanal SMS.