Zum Inhalt

Nachricht senden

Senden Sie Nachrichten über die SMSBAT-API mit dem Endpunkt „/bat/messagelist“.

Endpunkt

POST /bat/messagelist

Anforderungsstruktur

Der Anforderungstext ist ein JSON-Array von Nachrichtenobjekten:

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Your message text",
      "customerMessageId": "your-internal-id",
      "ttl": 3600
    }
  ]
}

Parameter

Erforderliche Parameter

Parameter Geben Sie ein Beschreibung
„von“ Zeichenfolge Alphanumerische Absender-ID
„zu“ Zeichenfolge Telefonnummer des Empfängers im E.164-Format (z. B. +380XXXXXXXXX)
„Typ“ Zeichenfolge Nachrichtentyp: „sms“, „viber_promo“, „viber_trans“, „viber_carousel“, „viber_survey“, „viber_otp“, „rcs“, „flashcall“
Text Zeichenfolge Nachrichteninhalt (für die meisten Typen erforderlich, für einige optional)

Optionale Parameter

Parameter Geben Sie ein Beschreibung
customerMessageId Zeichenfolge Ihre interne Kennung für die Nachverfolgung
ttl Ganzzahl Lebensdauer in Sekunden
messageData Objekt Typspezifische Konfiguration (variiert je nach Nachrichtentyp)

Authentifizierung

Wählen Sie eine von drei Authentifizierungsmethoden:

=== „API-Schlüsselheader“

```bash
curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -H "X-Authorization-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'
```

=== „HTTP-Basisauthentifizierung“

```bash
curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'
```

=== „API-Schlüssel als Passwort“

```bash
curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "@:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'
```

Antwort

Erfolgsantwort

{
  "messagelistId": 123456,
  "messages": [
    {
      "messageId": "abc123def456",
      "status": "accepted",
      "parts": 1,
      "customerMessageId": "your-internal-id",
      "to": "+380XXXXXXXXX"
    }
  ]
}

Antwortfelder

Feld Geben Sie ein Beschreibung
messagelistId Ganzzahl Eindeutiger Bezeichner für die Nachrichtenliste
messageId Zeichenfolge Eindeutiger Bezeichner für jede Nachricht
Status Zeichenfolge Nachrichtenstatus: „akzeptiert“, „abgelehnt“, „fehlgeschlagen“
„Teile“ Ganzzahl Anzahl der Nachrichtenteile (für SMS)
customerMessageId Zeichenfolge Ihre interne Kennung (falls angegeben)
„zu“ Zeichenfolge Telefonnummer des Empfängers

Nachrichtentypen

SMS

Einfache Textnachrichten:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Your SMS message text"
}

Viber-Promo

Werbebotschaften mit Rich Media:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Check out our new product!",
  "messageData": {
    "image": "https://example.com/image.jpg",
    "button": {
      "text": "View Product",
      "url": "https://example.com/product"
    }
  }
}

Viber-Transaktional

Transaktionsbenachrichtigungen:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Your order #12345 has been confirmed"
}

Viber OTP

Benachrichtigungen zu Einmalpasswörtern:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_otp",
  "messageData": {
    "code": "123456",
    "validity": 300
  }
}

Fehlerbehandlung

HTTP-Statuscodes

Code Beschreibung
200 Anfrage erfolgreich
400 Fehlerhafte Anfrage – ungültige Parameter
401 Nicht autorisiert – Authentifizierung fehlgeschlagen
429 Zu viele Anfragen – Ratenlimit überschritten
500 Interner Serverfehler

Fehlerantwort

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Invalid phone number format"
  }
}

Best Practices

Telefonnummernformat

Verwenden Sie für Telefonnummern immer das E.164-Format:

  • ✅ Richtig: „+380XXXXXXXXX“.
  • ❌ Falsch: „380XXXXXXXXX“, „0XXXXXXXXX“.

Nachrichtentext

  • Halten Sie SMS unter 160 Zeichen, um Mehrfachteile zu vermeiden
  • Verwenden Sie die UTF-8-Kodierung für internationale Zeichen
  • Testen Sie Sonderzeichen vor dem Massenversand

TTL (Time-to-Live)

– Legen Sie die entsprechende TTL für zeitkritische Nachrichten fest - OTP-Nachrichten: 300–600 Sekunden (5–10 Minuten) - Werbebotschaften: 3600–86400 Sekunden (1–24 Stunden)

Kundennachrichten-ID

  • Verwenden Sie für jede Nachricht eindeutige Kennungen
  • Hilft bei der Nachverfolgung und beim Debuggen
  • Nützlich für die Korrelation mit den Aufzeichnungen Ihres Systems

Tarifbegrenzungen

Kontaktieren Sie Ihren Account Manager für Informationen zu:

  • Nachrichten pro Sekunde
  • Nachrichten pro Tag
  • Gleichzeitige Verbindungen

Nächste Schritte