Gesprächsstatus aktualisieren

Verwenden Sie die API toggle_status, um den Status einer angegebenen Konversation zu ändern. Der Server prüft anhand der Zustandsübergangsmatrix STATUS_TRANSITIONS, ob der Zielstatus gültig ist.

Anfragemethode

POST

Endpoint

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/{conversation_id}/toggle_status

Authentifizierung

Ausführliche Informationen finden Sie in der Beschreibung der Authentifizierungsmethode unter API Overview.

Anfrage

Anfragebeispiel

curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/{conversation_id}/toggle_status' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)' \ -d '{ "status": "resolved", "snoozed_until": 1715000000 }'

              
              curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/{conversation_id}/toggle_status' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
-d '{
    "status": "resolved",
    "snoozed_until": 1715000000
}'

Diesen Codeblock im schwebenden Fenster anzeigen

Anfrage-Header

Field	Type	Description
Authorization	string	Verwenden Sie `Authorization: Basic base64(API Key:API Secret)` zur Authentifizierung. Öffnen Sie die API-Key-Seite, um den API Key und das API Secret zu erhalten, verbinden Sie beide mit einem Doppelpunkt und kodieren Sie das Ergebnis anschließend in Base64.
Content-Type	application/json	Inhaltstyp. Verwenden Sie `application/json` für Klartextnachrichten.

Pfadparameter

Field	Type	Required	Description
conversation_id	string	Yes	Konversations-ID.

Anfrage-Body-Parameter

Field	Type	Required	Description
status	string	Yes	Zielstatus. Siehe die Enum-Werte unten.
snoozed_until	integer	No	Wird nur wirksam, wenn `status=snoozed`. UNIX-Zeitstempel (Sekunden). Wenn der Wert ausgelassen wird, wird die Konversation auf unbestimmte Zeit zurückgestellt.
sender_type	string	No	Nur für die interne serverseitige Identifikation. Wenn der Aufrufer `AgentBot` ist, der aktuelle Status `pending` ist und der Zielstatus `open` ist, wird der Ablauf `bot_handoff!` ausgelöst und das Ereignis `CONVERSATION_BOT_HANDOFF` gesendet.

status-Enum-Werte

Value	Meaning
open	In Bearbeitung
resolved	Gelöst
pending	Ausstehende Bearbeitung durch Bot/Agent
snoozed	Zurückgestellt
closed	Geschlossen (archiviert)

Zustandsübergangsmatrix (STATUS_TRANSITIONS)

Current Status	Allowed Target Status
open	`open`, `resolved`, `pending`, `snoozed`
resolved	`resolved`, `open`, `pending`, `snoozed`, `closed`
pending	`pending`, `open`, `resolved`, `snoozed`
snoozed	`snoozed`, `open`, `resolved`, `pending`
closed	`closed`, `open`

Wichtige Einschränkungen

resolved ist der einzige erforderliche Ausgangszustand für den Wechsel zu closed: open, pending und snoozed können nicht direkt auf closed gesetzt werden; sie müssen zuerst in resolved übergehen, bevor sie archiviert werden.
closed kann nur zurück zu open wechseln: Archivierte Konversationen können nicht direkt in andere aktive Zustände wie resolved, pending oder snoozed übergehen.
Das Setzen desselben Status ist idempotent: Wenn der Zielstatus dem aktuellen Status entspricht, wird die Validierung übersprungen und direkt ein Erfolg zurückgegeben. Es wird kein Callback ausgelöst.
Die Validierung wird auf der ActiveRecord-Modellebene über validate :status_transition_allowed, if: :will_save_change_to_status? implementiert und gilt für alle Pfade mit save!, update! sowie status= + save.

Antwort

Erfolgreiche Antwort

HTTP 200:

{ "meta": {}, "payload": { "success": true, "conversation_id": 45, "current_status": "resolved", "snoozed_until": null } }

              
              {
  "meta": {},
  "payload": {
    "success": true,
    "conversation_id": 45,
    "current_status": "resolved",
    "snoozed_until": null
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Antwortparameter

Field	Type	Description
success	boolean	Rückgabewert von `save`; `true`, wenn die Statusaktualisierung erfolgreich ist.
conversation_id	integer	Die `display_id` der Konversation (für das Konto sichtbare ID).
current_status	string	Der Konversationsstatus nach der Aktualisierung.
snoozed_until	integer / null	Der aktuell wirksame Zeitstempel für das Ende der Zurückstellung; immer `null`, wenn der Status nicht `snoozed` ist.

Fehlerantworten

HTTP Status Code	Trigger Condition
401	Nicht authentifiziert oder Authentifizierung fehlgeschlagen
403	Der aktuelle Benutzer hat keinen Zugriff auf den Posteingang, zu dem die Konversation gehört
404	Unter dem aktuellen Konto kann keine Konversation mit der entsprechenden `display_id` gefunden werden
422	`status` ist kein gültiger Enum-Wert, `snoozed_until` kann nicht geparst werden oder der Zielstatus verletzt die Matrix STATUS_TRANSITIONS

422-Antwortstruktur

Verletzt die Zustandsübergangsmatrix (stammt aus der Validierung auf Modellebene und wird von RequestExceptionHandler als full_messages gerendert):

{ "message": "Status can't transition from open to closed", "attributes": ["status"] }

              
              {
  "message": "Status can't transition from open to closed",
  "attributes": ["status"]
}

Diesen Codeblock im schwebenden Fenster anzeigen

Unbekannter status-Enum-Wert (stammt aus CustomExceptions::Conversation::InvalidStatus):

{ "message": "Invalid conversation status: \"foo\" ('foo' is not a valid status)" }

              
              {
  "message": "Invalid conversation status: \"foo\" ('foo' is not a valid status)"
}

Diesen Codeblock im schwebenden Fenster anzeigen

Ungültiges snoozed_until (stammt aus CustomExceptions::Conversation::InvalidSnoozedUntil):

{ "message": "Invalid snoozed_until: \"not-a-timestamp\" (invalid date)" }

              
              {
  "message": "Invalid snoozed_until: \"not-a-timestamp\" (invalid date)"
}

Diesen Codeblock im schwebenden Fenster anzeigen