Chats

Dieses Modul beschreibt die API-Endpunkte zur Verwaltung von Chats. Ein Chat kann mit verschiedenen Kontexten verbunden sein (z. B. Vertrag, Team, Support-Ticket), aber auch kontextlos sein. Die Endpunkte erlauben das Erstellen, Bearbeiten, Abrufen und Auflisten von Chats.

---

Gültige Attribute

Attribut	Beschreibung	Details
agents_enabled	KI-gestützte Agenten aktiviert	Kann derzeit nicht gesetzt werden. Mögliche Werte: true oder false.
context_id	ID des Chat-Kontextes	Kann nicht manuell gesetzt werden.
context_type	Typ des Chat-Kontextes	Kann nicht gesetzt werden. Zulässige Werte: 'contract' (Vertrag), 'direct_conversation' (Direktnachricht), 'offboarding' (Offboarding), 'onboarding' (Onboarding), 'support_ticket' (Support Ticket), 'team' (Team) oder null.
discarded_at	Zeitpunkt der Entfernung (oder null)	Kann nicht manuell gesetzt werden.
latest_message_id	ID der letzten Nachricht im Chat	Kann nicht gesetzt werden. Darf leer sein.
open	Offener oder geschlossener Chat	Kann nur beim Update gesetzt werden. Werte: true oder false.
subject	Betreff des Chats	Muss gesetzt werden.

---

Beziehungen

Folgende Beziehungen können mit dem Parameter include in den Request eingebunden werden:

Beziehung	Typ	Beschreibung
bookmark	has_one	Die Lesezeichenbeziehung zwischen dem Chat und dem aktuellen Benutzer, um herauszufinden, ob in dem Chat ungelesene Nachrichten vorhanden sind.
latest_message	belongs_to	Die letzte Nachricht im Chat.

---

Meta-Daten: Berechtigungen

Können über den meta[permissions]-Parameter in den Request eingebunden werden. Sie geben an, welche Aktionen der aktuelle Benutzer in einem Chat ausführen kann.

Gruppe	Beschreibung
actions	Gibt an, ob der Benutzer den Chat 'edit' (bearbeiten) kann.
chat_membership	Gibt an, ob der Benutzer Mitglieder im Chat verwalten (manage) kann
message	Gibt an, ob der Benutzer Nachrichten lesen (read) oder erstellen (create) darf

---

Erstellen

Mit diesem Endpunkt kannst du einen neuen, kontextlosen Chat erstellen.

---

Endpunkt

POST /api/v1/chats

---

Request

{
  "data": {
    "type": "chat",
    "attributes": {
      ...
    }
  }
}

---

Response

{
  "data": {
    "id": "556ed4f1-d99d-43da-ac2c-0317bd6b9b59",
    "type": "chat",
    "attributes": {
      ...
    }
  }
}

---

Bearbeiten

Mit diesem Endpunkt kannst du einen bestehenden Chat aktualisieren, z.B. den Betreff ändern oder den Status auf offen oder geschlossen setzen. Beachte, dass du keine Kontext-IDs oder -Typen manuell setzen kannst, da diese automatisch verwaltet werden.

---

Endpunkt

PUT /api/v1/chats/:chat_id

---

Parameter

Name	Beschreibung
chat_id	Die ID des Chats, der bearbeitet wird.

---

Response

{
  "data": {
    "id": "6d500de8-afc5-4816-ad8d-1b191b97bfd3",
    "type": "chat",
    "attributes": {
      ...
    }
  }
}

---

Anzeigen

Mit diesem Endpunkt kannst du die Details eines einzelnen Chats abrufen.

---

Endpunkt

GET /api/v1/chats/:chat_id

---

Parameter

Name	Beschreibung
chat_id	Die ID des Chats, der abgerufen wird.

---

Response

{
  "data": {
    "id": "6d500de8-afc5-4816-ad8d-1b191b97bfd3",
    "type": "chat",
    "attributes": {
      ...
    }
  }
}

---

Beispiele

Chat mit allen Berechtigungen abrufen:

GET /api/v1/chats/:chat_id?&meta[permissions]=actions,chat_membership,message

---

Chat mit Lesezeichen und letzter Nachricht abrufen:

GET /api/v1/chats/:chat_id?include=bookmark,latest_message

---

Auflisten

Mit diesem Endpunkt kannst du alle Chats abrufen, in denen der aktuelle Benutzer Mitglied ist.

---

Endpunkt

GET /api/v1/chats

---

Response

{
  "data": [
    {
      "id": "ff96a49e-c57c-4a89-a910-ddbd2f85c8fe",
      "type": "chat",
      "attributes": {
        ...
      }
    },
    {
      ...
    }
  ]
}

---

Beispiele

Alle Chats des aktuellen Benutzers auflisten:

GET /api/v1/chats

---

Alle offenen Chats auflisten:

GET /api/v1/chats?filter[open]=eq:true

---

Alle Chats mit ihren jeweiligen Lesezeichen und letzten Nachrichten auflisten:

GET /api/v1/chats?include=bookmark,latest_message

---

Alle Chats und die Aktionen, die der aktuelle Benutzer ausführen kann, auflisten:

GET /api/v1/chats?meta[permissions]=actions,chat_membership,message

---

Alle Chats, die den Begriff „Support“ im Betreff enthalten:

GET /api/v1/chats?filter[subject]=ct:Support