Nachrichten senden und empfangen

Diese Anleitung führt Sie von einem API-Schlüssel zu einem funktionierenden Zwei-Wege-Nachrichtenfluss: eine ausgehende Nachricht senden, die Zustellung verfolgen und die Antwort auf Ihrem eigenen Server empfangen. Das Beispiel nutzt SMS – dasselbe Dreischrittmuster (senden → verfolgen → empfangen) gilt auch für WhatsApp, RCS, Viber und E-Mail, jeweils über einen eigenen Endpunkt. Das werden Sie tun:

Eine Nachricht senden
Die Zustellung verfolgen
Eingehende Nachrichten empfangen
Auf eine eingehende Nachricht antworten

Voraussetzungen

Ein API-Schlüssel aus Einstellungen → API-Schlüssel. Verwenden Sie beim Erstellen einen Sandbox-Schlüssel (dv_test_sk_…) – Sandbox-Versende sind kostenlos und simuliert, und liefern deterministische Zustellbelege, sodass Sie sowohl den Erfolgs- als auch den Fehlerpfad durchspielen können. Für Produktion wechseln Sie auf einen Live-Schlüssel (dv_live_sk_…).
Eine Absendernummer, die auf Ihrem Kanal senden darf. Für SMS ist das eine SMS-fähige Nummer, die Sie besitzen (per Numbers API oder über Dashboard → Numbers suchen und kaufen). Lassen Sie from weg, dann wählt Orbit einen zum Ziel passenden Absender.
Eine öffentliche HTTPS-URL für den Empfangsschritt. Während der Entwicklung eignet sich jedes Tunneling-Tool.

Alle Anfragen gehen an eine einzige Basis-URL – Sandbox verwendet denselben Host; die Auswahl erfolgt über Ihren Schlüssel, nicht über eine andere Domain:

https://api.orbit.devotel.io/api/v1

Jede Anfrage trägt Ihren Schlüssel im X-API-Key-Header.

1. Eine Nachricht senden

Senden Sie eine SMS mit POST /messages/sms. Nur to und body sind erforderlich; from ist optional.

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-conf-98421" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "Your order #1234 has shipped. Reply STATUS for tracking."
  }'

Die Antwort lautet 202 Accepted – die Nachricht ist persistiert und zur Zustellung in der Warteschlange eingeordnet, noch nicht an den Mobilfunkanbieter übergeben. Die Felder liegen unter data; meta trägt die request_id, die Sie für den Support loggen sollten.

{
  "data": {
    "id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "status": "queued",
    "channel": "sms",
    "direction": "outbound",
    "segments": 1
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-07-20T00:00:00Z"
  }
}

Die id (msg_ gefolgt von 32 Hex-Zeichen) ist der Verweis für alle Folgeaufrufe – Statusabfragen, Zustell-Webhooks und der Message-Trace richten sich daran aus. Sandbox-Antworten fügen meta ein "test_mode": true hinzu.

Senden Sie bei jeder Sendung einen Idempotency-Key. Wenn Sie denselben Schlüssel und denselben Body innerhalb von 24 Stunden erneut senden, erhalten Sie die ursprüngliche Antwort zurück statt eine Duplikat-Sendung; bei einem anderen Body wird 409 IDEMPOTENCY_KEY_REUSED zurückgegeben.

Weitere Kanäle

Jeder Kanal hat unter der /messages-Präfix einen eigenen Endpunkt mit einer für diesen Kanal ausgelegten Body-Form. Es gibt keinen einzigen kanal-polymorphen Route – wählen Sie den Endpunkt, der zu Ihrem Kanal passt:

Kanal	Endpunkt	Referenz
SMS	`POST /messages/sms`	Messaging API
WhatsApp	`POST /messages/whatsapp`	WhatsApp-Kanal
RCS	`POST /messages/rcs`	RCS-Kanal
Viber	`POST /messages/viber`	Viber-Kanal
E-Mail	`POST /messages/email`	E-Mail-Kanal

2. Die Zustellung verfolgen

Eine in der Warteschlange befindliche Nachricht durchläuft einen Status-Lebenszyklus, bevor sie den Empfänger erreicht:

queued → sending → sent → delivered   (or failed / undelivered)

Es gibt zwei Wege, ihm zu folgen: Abfragen (Poll) Sie die Nachricht per ID:

curl https://api.orbit.devotel.io/api/v1/messages/msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Webhooks abonnieren (empfohlen – ohne Polling). Pro Statusübergang wird ein Ereignis ausgelöst; jedes trägt die Nachrichten-id und den neuen status:

message.sent – vom Mobilfunkanbieter angenommen
message.delivered – dem Gerät zugestellt bestätigt
message.failed – endgültiger Fehler (der status in der Nutzlast unterscheidet failed, undelivered, expired und submitted_no_receipt; error_code / error_message tragen ggf. den Providergrund)

Registrieren Sie einen Webhook-Endpunkt ein Mal, danach fließen die Ereignisse:

curl -X POST https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/orbit",
    "events": ["message.sent", "message.delivered", "message.failed", "message.received"],
    "secret": "whsec_your_signing_secret"
  }'

Ein Zustellereignis sieht so aus:

{
  "id": "evt_abc123",
  "type": "message.delivered",
  "created_at": "2026-07-20T12:00:00Z",
  "data": {
    "message_id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "channel": "sms",
    "status": "delivered",
    "is_terminal": true,
    "timestamp": "2026-07-20T12:00:00Z"
  }
}

Prüfen Sie den X-Orbit-Signature-Header, bevor Sie einer Nutzlast vertrauen, und deduplizieren anhand der Ereignis-id – die Zustellung erfolgt mindestens ein Mal (at-least-once). Siehe Webhook-Sicherheit für das Verifikations-Snippet.

3. Eingehende Nachrichten empfangen

Wenn jemand auf Ihre Nummer antwortet (oder Ihnen zuerst schreibt), zeichnet Orbit eine eingehende Nachricht auf und – falls Sie im Schritt oben message.received abonniert haben – sendet sie als POST an Ihre Webhook-URL:

{
  "id": "evt_def456",
  "type": "message.received",
  "created_at": "2026-07-20T12:01:00Z",
  "data": {
    "message_id": "msg_inb_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
    "channel": "sms",
    "from": "+14155552671",
    "to": "+18005551234",
    "body": "STATUS"
  }
}

Die eingehende Nachricht ist auch abfragbar – listen Sie alles Empfangene mit dem Filter direction=inbound:

curl "https://api.orbit.devotel.io/api/v1/messages?direction=inbound&channel=sms" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Das eingehende Routing ist automatisch für Nummern, die Sie auf Orbit besitzen – eine Antwort auf eine Ihrer Absendernummern wird erfasst und bei message.received-Abonnement an Ihren Webhook zugestellt. Eine eigene Eingangs-URL-Kabelverlegung pro Nummer ist nicht erforderlich.

4. Auf eine eingehende Nachricht antworten

Antworten ist nur ein weiterer Sendeaufruf, adressiert zurück an den eingehenden from. Tauschen Sie to und from und rufen Sie POST /messages/sms erneut auf:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "Order #1234 is out for delivery, arriving today by 5pm."
  }'

Beide Nachrichten teilen eine Konversation, sodass Sie – sobald der Thread existiert – den vollständigen Rücklauf mit dem Filter conversation_id auf GET /messages ziehen können.

Häufige Fehler

Jeder Fehler nutzt dieselbe Form – matchen Sie auf error.code (eine GROSSBUCHSTABEN-Konstante) und loggen Sie meta.request_id:

Code	HTTP	Bedeutung	Lösung
`INVALID_API_KEY`	401	Schlüssel widerrufen, falsche Umgebung oder Tippfehler	Prüfen Sie Einstellungen → API-Schlüssel
`INVALID_PHONE_NUMBER`	422	`to` ist kein gültiges E.164 oder nicht erreichbar	Validieren Sie die Nummer vor dem Senden
`NOT_SMS_CAPABLE`	422	Der Absender ist nicht SMS-fähig (z. B. toll-free ohne 10DLC)	Nummer registrieren oder wechseln
`INSUFFICIENT_BALANCE`	402	Guthaben unter dem Kanalmindest	Wallet aufladen
`RATE_LIMITED`	429	Zu viele Sendungen	Beachten Sie `details.retry_after` (Sekunden)
`VALIDATION_ERROR`	422	Body-Form ungültig	Lesen Sie `details.issues` pro Feld

Vollständige Liste: Fehlercodes.

Nächste Schritte

Messaging API-Referenz – jeder Nachrichtenendpunkt und jedes Feld
Nachrichtenstatus-Lebenszyklus – die vollständige Statusmenge je Kanal
Webhooks-Übersicht – Wiederholungen, Zustellgarantien und der Ereigniskatalog
API-Integration – Sandbox, Idempotenz, Paginierung und SDKs für jeden Kanal
Ratenlimits – pro-Kanal-Grenzen und Wiederholungs-Header

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Nachrichten senden und empfangen

Nachrichten senden und empfangen

Voraussetzungen

1. Eine Nachricht senden

Weitere Kanäle

2. Die Zustellung verfolgen

3. Eingehende Nachrichten empfangen

4. Auf eine eingehende Nachricht antworten

Häufige Fehler

Nächste Schritte

​Nachrichten senden und empfangen

​Voraussetzungen

​1. Eine Nachricht senden

​Weitere Kanäle

​2. Die Zustellung verfolgen

​3. Eingehende Nachrichten empfangen

​4. Auf eine eingehende Nachricht antworten

​Häufige Fehler

​Nächste Schritte

Nachrichten senden und empfangen

Voraussetzungen

1. Eine Nachricht senden

Weitere Kanäle

2. Die Zustellung verfolgen

3. Eingehende Nachrichten empfangen

4. Auf eine eingehende Nachricht antworten

Häufige Fehler

Nächste Schritte