Zum Hauptinhalt gehen

✉️ Nachrichten-Management – /messages API

Brevis Support
Aktualisiert

Die messages-API ermöglicht das Senden, Abfragen, Anzeigen und Löschen von Nachrichten über verschiedene Provider wie SMS oder Telegram. Sie unterstützt Einzel- und Gruppenzustellungen sowie verschiedene Nachrichtentypen.

🔐 Authentifizierung

Alle Endpunkte unter /messages erfordern:

  • Bearer Auth (Authorization: Bearer <token>)

  • oder HTTP Basic Auth

📤 POST /messages – Nachricht senden

Beschreibung

Sendet eine Nachricht an einen oder mehrere Empfänger über den gewählten Provider.

Request Body

{
  "recipients": [
    {
      "to": "students_group",
      "target": "group"
    }
  ],
  "text": "Hello dear students , Your English course begins at 10/10/2035.",
  "provider": "sms",
  "type": "ring"
}
Feld Typ Beschreibung
recipients Array[Object] Empfänger-Definitionen (z. B. Gruppe oder Einzelperson)
to String Zielkennung, z. B. Telefonnummer oder Gruppenname
target String Typ des Ziels: user oder group
text String Nachrichtentext
provider String Versandweg: sms oder telegram
type String Nachrichtentyp: z. B. ring, flash (optional)

Antwort 201 Created

[
  {
    "id": "5f50a964cf7e3",
    "type": "sent",
    "text": "Hello Mr. John , your car is ready for pick up",
    "provider": "telegram",
    "timestamp": 1599121764,
    "isFlash": true,
    "isRing": true,
    "senders": [...],
    "recipients": [...]
  }
]

Hinweis

  • Die Rückmeldung bedeutet, dass das System die Nachricht verarbeitet hat – nicht zwingend, dass der Provider sie erfolgreich zustellt.

📥 GET /messages – Nachrichten abfragen

Beschreibung

Listet Nachrichten nach Filterkriterien auf (Status, Provider, Zeitraum, Nummer etc.).

Query-Parameter

Parameter Typ Beschreibung
type Array[String] sent, queued, failed, incoming (Standard: incoming)
provider Array[String] sms, telegram (Standard: beide)
number String Telefonnummer des Senders/Empfängers
user String Benutzername oder ID des Senders
start_date String Startdatum (Format: Unix Time Stamp)
end_date String Enddatum (Format: Unix Time Stamp)

Antwort 200 OK

[
  {
    "id": "5f50a964cf7e3",
    "type": "sent",
    "text": "...",
    "provider": "telegram",
    "timestamp": 1599121764,
    "senders": [...],
    "recipients": [...]
  }
]

📄 GET /messages/{id} – Einzelne Nachricht abrufen

Beschreibung

Gibt die vollständigen Details zu einer bestimmten Nachricht zurück.

Pfadparameter

Parameter Beschreibung
id Die eindeutige Nachrichten-ID

Beispielantwort

(Siehe Beispiel von GET /messages, identisch in Struktur.)

🗑️ DELETE /messages/{id} – Nachricht löschen

Beschreibung

Löscht eine Nachricht dauerhaft anhand ihrer ID.

Pfadparameter

Parameter Beschreibung
id Die ID der zu löschenden Nachricht

Antwort 204 No Content

Die Nachricht wurde erfolgreich gelöscht.

❗ Mögliche Fehlercodes (alle Endpunkte)

Code Beschreibung
400 Ungültige Anfrage
401 Nicht authentifiziert
403 Zugriff verweigert
404 Ressource nicht gefunden
422 Semantische Fehler in der Anfrage
503 Dienst derzeit nicht verfügbar

Beispiel-Fehlermeldung

{
  "code": 0,
  "message": "string",
  "reasons": ["string"]
}

📊 Tipps zur Integration

  • Nutze queued, sent, failed, um Status-Monitoring zu bauen.

  • Empfängergruppen vereinfachen Massenversand an definierte Teams.

  • Kombiniere mit /user/me, um eigene Nachrichten auszulesen.

  • Erweitere mit Webhooks oder einem Polling-Mechanismus, um Zustellstatus asynchron abzufragen.

Verknüpfung mit

Verwandte Beiträge

Kommentare

0 Kommentare

Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.