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