Konversationen anhand der Kontaktkennung abfragen

Externe Systeme können anhand der Geschäftskennung, E-Mail-Adresse oder vollständigen Telefonnummer eines Kontakts die zugehörigen IDs regulärer Konversationen, deren Erstellungszeitpunkte und aktuelle Status abfragen. Die zurückgegebenen Konversations-IDs können direkt mit den vorhandenen V2-APIs für Konversationsdetails, Nachrichten und weitere Funktionen verwendet werden.

Anfragemethode

GET

Anfrage-URL

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup

Authentifizierung

Diese API verwendet HTTP-Basic-Authentifizierung. Übergeben Sie Authorization im Anfrage-Header mit dem API-Schlüssel als Benutzernamen und dem API-Geheimnis als Passwort. Das den Zugangsdaten zugeordnete Projekt bestimmt den Abfragebereich. Daher müssen Sie die Projekt-ID nicht im Pfad angeben. Weitere Informationen finden Sie in der API-Übersicht.

Wenn die Anfrage account_id enthält, muss dessen Wert mit dem den Zugangsdaten zugeordneten Projekt übereinstimmen. Andernfalls wird 401 zurückgegeben.

Anfrage

Anfragebeispiel

              
              curl -X GET 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/lookup?type=identifier&value=Customer_123&page=1&page_size=20' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)'

            

Bei der Abfrage anhand einer Telefonnummer muss + URL-codiert werden:

              
              GET /api/v2/accounts/conversations/lookup?type=phone&value=%2B15551234567

            

Anfrage-Header-Parameter

Abfrageparameter

Abgleichregeln

• identifier: Groß- und Kleinschreibung werden berücksichtigt. Der ursprüngliche Wert bleibt erhalten. Ein Abgleich anhand von Teilzeichenfolgen oder Platzhaltern wird nicht unterstützt.
• email: Führende und nachgestellte Leerzeichen werden entfernt. Das E-Mail-Format wird geprüft, bevor ein exakter Abgleich ohne Berücksichtigung der Groß- und Kleinschreibung erfolgt.
• phone: Führende und nachgestellte Leerzeichen werden zunächst entfernt. Die Nummer muss vollständig sein, + und die Landesvorwahl enthalten und dem Format von phone_number des Kontakts entsprechen. Die API ergänzt keine Standardlandesvorwahl und unterstützt keinen Abgleich anhand der letzten Ziffern einer Nummer.
• GET-Parameter müssen korrekt URL-codiert werden. Insbesondere muss + in Telefonnummern als %2B codiert werden.

Abfragebereich und Sortierung

Kontakte und Konversationen werden ausschließlich innerhalb des den Zugangsdaten zugeordneten Projekts abgefragt. Die API gibt alle regulären Konversationen zurück, die dem Kontakt über sämtliche Posteingänge des Projekts zugeordnet sind (conversation_category=chat). Ticket-Konversationen sind ausgeschlossen. Es wird nicht nach dem aktuellen Agenten, dem zuständigen Bearbeiter oder dem Posteingang gefiltert.

Reguläre Konversationen werden mit allen Status zurückgegeben: open, resolved, pending, snoozed und closed. Diese API bietet keine Statusfilterung. Selbst wenn status angegeben wird, werden die Ergebnisse nicht eingeschränkt.

Die Ergebnisse werden absteigend nach dem Erstellungszeitpunkt der Konversation sortiert. Bei gleichen Erstellungszeitpunkten erfolgt die Sortierung absteigend nach dem internen Primärschlüssel der Konversation. Solange sich die Daten nicht ändern, bleibt die Reihenfolge der Seitennavigation stabil. Seitenbasierte Seitennavigation garantiert keinen konsistenten Datenstand, während gleichzeitig Konversationen erstellt oder gelöscht werden.

Antwort

Erfolgreiche Antwort

HTTP 200:

              
              {
  "meta": {
    "count": 2,
    "current_page": 1,
    "page_size": 20,
    "total_pages": 1
  },
  "payload": [
    {
      "id": 202609000000002,
      "created_at": 1788739200,
      "status": "closed",
      "inbox_id": 12,
      "contact_id": 901
    },
    {
      "id": 202609000000001,
      "created_at": 1788652800,
      "status": "open",
      "inbox_id": 10,
      "contact_id": 901
    }
  ]
}

            

Antwortparameter

Wenn der Kontakt nicht existiert, keine regulären Konversationen hat oder die angeforderte Seite die Gesamtzahl der Seiten überschreitet, wird HTTP 200 zurückgegeben. In allen drei Fällen ist payload ein leeres Array; meta.count enthält stets die tatsächliche Gesamtzahl der Ergebnisse.

Die Antwort enthält nur die oben aufgeführten Felder und gibt keine Nachrichten, Anhänge oder persönlichen Kontaktinformationen zurück.

Fehlerantwort

Fehlerantworten verwenden die folgende Struktur. Fehlerbeschreibungen geben den Abfragewert nicht wieder:

              
              {
  "error": "Error description"
}

            

Nutzungshinweise

• Diese API ergänzt ausschließlich die Abfragefunktion und verändert keine Kontakt- oder Konversationsdaten.
• Die API unterstützt keine Kontaktsuche mittels unscharfen Abgleichs. Stellen Sie sicher, dass der im externen System gespeicherte identifier, die E-Mail-Adresse oder die Telefonnummer mit dem entsprechenden Kontaktattribut in LiveDesk übereinstimmt.
• Um Konversationen aus den Abfrageergebnissen zu bearbeiten, verwenden Sie beim Aufrufen der entsprechenden V2-APIs payload[].id aus der Antwort als externe Konversations-ID.