SMS per API senden: Beispiele für Python, Node.js, PHP, 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+ (integriertes fetch)
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(); // Nachrichten-ID als Klartext

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  # Nachrichten-ID als Klartext, kein 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,
)

Wie zähle ich Segmente vor dem Senden?

Rufen Sie POST /sms/identify mit der Nachricht auf. Der Aufruf liefert die erkannte Kodierung, die Zeichenzahl, die Segmentzahl und das Limit pro Segment.

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
}

Sie können smsParts (aus smscount), charCount und charLimit in eine Sendeanfrage übernehmen. GSM-7-Text kann in der Antwort als GSM-7 bezeichnet sein; senden Sie ihn als TEXT.

Wie sende ich an viele Nummern?

Nutzen Sie POST /sms/sendbulk, eine multipart/form-data-Anfrage mit einer Empfängerdatei und einem JSON-String mit Einstellungen.

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())

Die Antwort enthält bulkSessionId und ein Objekt bulkListInfo mit total, validCount, invalidCount und duplicate. Speichern Sie bulkSessionId bei der Kampagne. Aufträge können mit den Endpunkten der Referenz aufgelistet, pausiert, fortgesetzt und abgebrochen werden. Vor einem großen Versand können Sie Nummern außerdem mit POST /sms/lookup prüfen; siehe unseren HLR-Lookup-Leitfaden.

Wie erhalte ich den Zustellstatus?

Zustellstatus werden an die in Ihrem Account konfigurierte Webhook-URL gesendet. Eine Nachricht durchläuft SUBMITTED und SENT bis DELIVERED oder endet als FAILED oder REJECTED. Sie nennen unserem Team die öffentliche HTTPS-URL, und Reseller können einen Webhook pro Unterkonto haben.

Die Payload-Felder unterscheiden sich je Kanal, und die API-Spezifikation definiert kein einheitliches Webhook-Schema. Protokollieren Sie daher zuerst den Roh-Body und ordnen Sie Felder anhand eines echten Ereignisses Ihres Accounts zu. Ein minimaler Empfänger speichert das Ereignis und bestätigt schnell:

import express from "express";

const app = express();

app.post("/webhooks/omnichannels", express.json(), async (req, res) => {
  await saveStatusEvent(req.body); // Ihr Speicher; asynchron verarbeiten
  res.sendStatus(200);             // schnell bestätigen
});

app.listen(3000);

Machen Sie die Verarbeitung idempotent, denn derselbe Status kann zweimal eintreffen, und lassen Sie ein verspätetes SENT nie ein gespeichertes DELIVERED überschreiben. War Ihr Endpunkt nicht erreichbar, sendet POST /sms/resendDlr die Berichte für einen Datumsbereich erneut:

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"
  }'

Mehr dazu im Webhooks-Leitfaden und in der Erklärung der Nachrichten-Zustellstatus.

Wie behandle ich Fehler und vermeide Duplikate?

Behandeln Sie zuerst den HTTP-Status, dann den Fehler-Body. Wiederholen Sie nur bei Netzwerkfehlern, 429 und 5xx.

Von der API ausgelöste Fehler nutzen einen JSON-Body mit fünf Feldern: status, error, message, errorCode und requestUri. Das dokumentierte Standardlimit der REST-API liegt bei dauerhaft 200 Anfragen pro Sekunde; die Limits Ihres Accounts werden mit Ihren Zugangsdaten bestätigt.

Die API akzeptiert keinen Idempotency-Key. Eine Anfrage kann gelingen, während ihre Antwort verloren geht, und eine blinde Wiederholung sendet dann doppelt. Schreiben Sie vor dem Aufruf eine ausstehende Zeile mit Ihrer eigenen Vorgangs-ID, speichern Sie die zurückgegebene Nachrichten-ID und prüfen Sie nach einem Timeout, ob ein Webhook-Status vorliegt, bevor Sie erneut senden. Setzen Sie bei Massenversand allowDuplicate auf false. Details stehen unter Fehler und Limits.

Praxisbeispiel: Login-Codes für eine regionale App

„Souq Rafiq“ (fiktiv), ein Händler in den VAE, sendet Login-Codes per SMS.

1. Der Auth-Dienst erzeugt einen sechsstelligen Code, speichert einen Hash mit fünf Minuten Gültigkeit und schreibt eine pending-Sendezeile.
2. Er ruft /sms/sendSms mit messageType=UNICODE für arabische Nutzer und TEXT für englische Nutzer auf.
3. Bei 200 speichert er die Nachrichten-ID.
4. Der Webhook-Handler markiert die Zeile als DELIVERED, FAILED oder REJECTED.
5. Ist der Status nach kurzer Wartezeit nicht DELIVERED, bietet die App ein erneutes Senden und, falls konfiguriert, einen anderen Kanal an. Siehe Kanal-Fallback.
6. Ratenlimits für Code-Anfragen je Nummer und je IP schützen vor Missbrauch; siehe Prävention von SMS-Pumping.

Welche typischen Fehler gibt es?

• r.json() auf die Sendeantwort aufrufen. Sie ist Klartext.
• Falsche Feldnamen. Verwenden Sie senderId, destinationNumber und message; Felder wie to, from oder text gehören nicht zu diesem Endpunkt.
• Pluszeichen und führende Nullen in Nummern.
• UNICODE vergessen bei Arabisch, was den Text verstümmelt.
• Nicht registrierte Sender IDs. Manche Länder blockieren oder ersetzen sie; prüfen Sie die Sender-ID-Regeln für Ihr Zielland und bitten Sie uns, die Registrierung zu übernehmen.
• 200 als zugestellt werten.
• Token in einer mobilen App oder im Browser, wo jeder es auslesen kann.
• Grenzen: Dieser Leitfaden zeigt die gängige Anfrage. Optionale Felder wie Planungsformate sollten Sie mit unserem Team bestätigen.

So unterstützt OmniChannels.ai

OmniChannels.ai sendet A2P-SMS über die direkte Netzanbindung von BroadNet, mit Zwei-Wege-SMS, Sender IDs, Unicode und Arabisch, HLR-Lookup und SMPP 3.4 für hohe Volumen. Die REST-API unter https://api.broadnet.me nutzt ein Bearer-Token und deckt auch WhatsApp, RCS und weitere Kanäle ab, wobei Zustellstatus in einem einheitlichen Webhook-Format normalisiert werden. Unser Team bereitet Sender-ID-Registrierungen gemeinsam mit Ihnen vor. Siehe die SMS-API-Referenz oder den SMS-Kanal.