Rechercher des conversations par identifiant de contact

Les systèmes externes peuvent rechercher les ID des conversations régulières associées, leurs heures de création et leurs statuts actuels pour un contact à l'aide de l'identifiant métier du contact, de son adresse e-mail ou de son numéro de téléphone complet. Les ID de conversation renvoyés peuvent être utilisés directement avec les API V2 existantes pour obtenir les détails des conversations, les messages, etc.

Méthode de requête

GET

URL de requête

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

Authentification

Cette API utilise l'authentification HTTP Basic. Transmettez Authorization dans l'en-tête de la requête, avec la clé API comme nom d'utilisateur et le secret API comme mot de passe. Le projet associé aux identifiants définit le périmètre de recherche ; vous n'avez donc pas besoin d'inclure l'ID du projet dans le chemin. Pour plus de détails, consultez la présentation de l'API.

Si account_id est inclus dans la requête, sa valeur doit correspondre au projet associé aux identifiants ; sinon, un code 401 est renvoyé.

Requête

Exemple de requête

              
              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)'

            

Lors d'une recherche par numéro de téléphone, + doit être encodé dans l'URL :

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

            

Paramètres d'en-tête de requête

Paramètres de requête

Règles de correspondance

• identifier : sensible à la casse. La valeur d'origine est conservée et la correspondance par sous-chaîne ou par caractère générique n'est pas prise en charge.
• email : les espaces en début et en fin de chaîne sont supprimés, et le format de l'adresse e-mail est validé avant d'effectuer une correspondance exacte, insensible à la casse.
• phone : les espaces en début et en fin de chaîne sont d'abord supprimés. Le numéro doit être complet, inclure + et l'indicatif du pays, et correspondre au format du phone_number du contact. L'API n'ajoute pas d'indicatif de pays par défaut et ne prend pas en charge la correspondance sur les derniers chiffres d'un numéro.
• Les paramètres GET doivent être correctement encodés dans l'URL. En particulier, + dans les numéros de téléphone doit être encodé en %2B.

Périmètre de recherche et tri

Les contacts et les conversations sont recherchés uniquement dans le projet associé aux identifiants. L'API renvoie toutes les conversations régulières associées au contact dans toutes les boîtes de réception du projet (conversation_category=chat), à l'exclusion des conversations de ticket et sans filtrage par agent actuel, agent assigné ou boîte de réception.

Les conversations régulières dans tous les statuts sont renvoyées : open, resolved, pending, snoozed et closed. Cette API ne permet pas de filtrer par statut ; même si status est fourni, les résultats ne sont pas restreints.

Les résultats sont triés par heure de création de la conversation par ordre décroissant. Lorsque les heures de création sont identiques, les résultats sont triés par clé primaire interne de la conversation, également par ordre décroissant. L'ordre de pagination reste stable tant que les données ne changent pas. La pagination par pages ne garantit pas un instantané cohérent pendant que des conversations sont créées ou supprimées simultanément.

Réponse

Réponse réussie

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
    }
  ]
}

            

Paramètres de réponse

Si le contact n'existe pas, si le contact n'a aucune conversation régulière ou si la page demandée dépasse le nombre total de pages, HTTP 200 est renvoyé. Dans ces trois cas, payload est un tableau vide ; meta.count conserve toujours le nombre total réel de résultats.

La réponse contient uniquement les champs listés ci-dessus et ne renvoie ni messages, ni pièces jointes, ni informations personnelles du contact.

Réponse d'erreur

Les réponses d'erreur utilisent la structure suivante. Les descriptions d'erreur ne répètent pas la valeur de recherche :

              
              {
  "error": "Description de l'erreur"
}

            

Notes d'utilisation

• Cette API ajoute uniquement une fonctionnalité de recherche et ne modifie pas les données de contact ou de conversation.
• L'API ne prend pas en charge la recherche de contacts via une correspondance approximative. Assurez-vous que l'identifier, l'adresse e-mail ou le numéro de téléphone stocké par le système externe correspond bien à l'attribut de contact correspondant dans LiveDesk.
• Pour traiter les conversations dans les résultats de recherche, utilisez payload[].id de la réponse comme ID de conversation externe lors de l'appel des API V2 correspondantes.