API-Referenz

Erste Schritte

Drei Dinge stehen zwischen einem neuen Konto und einer zugestellten Nachricht: ein Token, etwas Guthaben und ein Schlüssel. Keines davon erfordert einen Menschen.

1. Erstellen Sie ein Konto — Ihr Browser generiert den Token, und dieser Token ist das Konto.
2. Laden Sie es auf. $40 Minimum, in jeder der Kryptowährungen auf die Zahlungsseite.
3. Erstellen Sie einen API-Schlüssel im Dashboard. Er wird einmal angezeigt; wir speichern nur seinen Hash, genau wie beim Token.

Authentifizierung

Bearer-Token bei jeder Anfrage. Der Schlüssel identifiziert das Konto; es gibt keinen zweiten Faktor, keine Signatur der Anfrage und keine IP-Allowlist — der Schlüssel ist das gesamte Berechtigungsmerkmal, behandeln Sie ihn also so.

Authorization: Bearer ws_live_9f2c…

Nachrichten senden

POST/v1/messages

Ein Aufruf, ein oder mehrere Empfänger, gemischte Zielländer. Jeder Empfänger wird zum Preis seines eigenen Ziellands berechnet, pro Segment abgerechnet. Der Aufruf wird als Ganzes angenommen oder abgelehnt; er berechnet Ihnen nie nur einen Teil.

Request-Body

Beispiel

# one call, many recipients, mixed destinations
curl -X POST https://api.worldsms.io/v1/messages \
  -H "Authorization: Bearer $WORLDSMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "ACME",
    "to":   ["+447700900123", "+33612345678"],
    "text": "Your code is 480913"
  }'

{
  "batch_id": "b_7Kq2xR9wLm",
  "accepted": 2,
  "rejected": 0,
  "segments": 1,
  "cost_usd": 0.0353
}

Stapelverarbeitung

Ein Batch wird sofort angenommen und läuft mit 200 Nachrichten pro Minute und Konto ab, sodass 50.000 Empfänger etwa 4 Std. 10 Min dauern. Zeitkritischer Traffic sollte nicht hinter einem Marketing-Versand in der Warteschlange stehen: Verwenden Sie dafür einen separaten Schlüssel.

Nachrichtenstatus

GET/v1/messages/{batch_id}

Polling wird unterstützt und ist ratenbegrenzt; Webhooks sind der vorgesehene Weg. Die Antwort fasst den Batch zusammen und listet den Status je Empfänger auf.

{
  "batch_id":    "b_7Kq2xR9wLm",
  "status":      "done",
  "sending":     0,
  "delivered":   1,
  "undelivered": 1,
  "refund_usd":  0.0216
}

refund_usd wird einmal abgerechnet, wenn der Batch abgeschlossen ist. Es ist bereits wieder in Ihrem Kontostand, sobald Sie es lesen können.

Kontostand

GET/v1/balance

Prüfen Sie das vor einem großen Versand. Guthaben wird intern in ganzzahligen Mikro-Dollar geführt — Preise gehen auf vier Nachkommastellen, und eine Gleitkommazahl hat in einem Buchungsjournal nichts verloren — und hier auf sechs Stellen gerundet zurückgegeben.

{ "balance_usd": 412.905400, "currency": "USD" }

Zustellbestätigungen

Pro Empfänger wird eine Zustellbestätigung ausgegeben, sobald der Netzbetreiber sie meldet. Das sind die einzigen vier Zustände; es gibt keine Kategorie „unbekannt“, die stillschweigend „wir haben sie verloren“ bedeutet.

Nummern, die sich nie einem bepreisten Ziel zuordnen lassen, werden schon bei der Übermittlung abgelehnt und treten in diesen Lebenszyklus gar nicht erst ein — sie werden nicht erst berechnet und dann erstattet, sie werden schlicht nicht berechnet.

Webhooks

Legen Sie im Dashboard oder pro Batch mit callback_url einen Endpunkt fest. Wir senden JSON per POST und erwarten einen 2xx innerhalb von 5 Sekunden. Nicht-2xx wird sechsmal mit exponentiellem Backoff über etwa eine Stunde wiederholt und dann verworfen.

Payload

{
  "event":     "message.delivered",
  "batch_id":  "b_7Kq2xR9wLm",
  "to":        "+447700900123",
  "destination": "gb",
  "segments":  1,
  "cost_usd":  0.0137,
  "reference": "order-4471",
  "ts":        1785312041
}

Signatur wird überprüft

Jede Zustellung trägt X-WorldSMS-Signature und X-WorldSMS-Timestamp. Die Signatur ist HMAC-SHA256(timestamp + "." + body) unter Verwendung Ihres Webhook-Secrets. Vergleichen Sie in konstanter Zeit und lehnen Sie einen mehr als fünf Minuten alten Zeitstempel ab, damit eine abgefangene Zustellung Ihnen nicht später erneut vorgespielt werden kann.

// $secret is the webhook secret from the dashboard
$raw  = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_WORLDSMS_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_WORLDSMS_SIGNATURE'] ?? '';

// A stale timestamp is a replay, however well it is signed.
if (abs(time() - (int) $ts) > 300) { http_response_code(408); exit; }

$mine = hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (!hash_equals($mine, $sig)) { http_response_code(401); exit; }

http_response_code(204);

Fehler

Jeder Fehler liefert einen JSON-Body mit einem stabilen error-Slug zurück. Werten Sie den Slug aus, niemals den Text — der Text darf sich verbessern.

{
  "error":       "insufficient_credit",
  "message":     "Batch costs $84.20, balance is $12.05.",
  "required_usd": 84.20,
  "balance_usd":  12.05
}

Limits

Ratenlimits gelten für API-Aufrufe, nicht für Nachrichten: Ein Aufruf mit 5.000 Empfängern zählt als eine Anfrage gegen das Limit.