Consultar conversaciones por identificador de contacto

Los sistemas externos pueden consultar los ID de las conversaciones normales asociadas a un contacto, sus fechas de creación y sus estados actuales mediante el identificador de negocio, la dirección de correo electrónico o el número de teléfono completo del contacto. Los ID de conversación devueltos se pueden utilizar directamente con las API V2 existentes para obtener detalles de conversaciones, mensajes y otros datos.

Método de solicitud

GET

URL de la solicitud

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

Autenticación

Esta API utiliza autenticación HTTP Basic. Incluya Authorization en la cabecera de la solicitud, con la clave de API como nombre de usuario y el secreto de API como contraseña. El proyecto asociado a las credenciales define el ámbito de la consulta, por lo que no es necesario incluir el ID del proyecto en la ruta. Para obtener más información, consulte Descripción general de la API.

Si se incluye account_id en la solicitud, su valor debe coincidir con el proyecto asociado a las credenciales; de lo contrario, se devuelve 401.

Solicitud

Ejemplo de solicitud

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

            

Al consultar por número de teléfono, + debe codificarse para URL:

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

            

Parámetros de la cabecera de la solicitud

Parámetros de consulta

Reglas de coincidencia

• identifier: Distingue entre mayúsculas y minúsculas. Se conserva el valor original y no se admiten coincidencias por subcadenas ni comodines.
• email: Se eliminan los espacios en blanco iniciales y finales y se valida el formato del correo electrónico antes de realizar una coincidencia exacta que no distingue entre mayúsculas y minúsculas.
• phone: Primero se eliminan los espacios en blanco iniciales y finales. El número debe estar completo, incluir + y el código de país, y coincidir con el formato de phone_number del contacto. La API no añade un código de país predeterminado ni admite coincidencias por los últimos dígitos de un número.
• Los parámetros GET deben codificarse correctamente para URL. En particular, + en los números de teléfono debe codificarse como %2B.

Ámbito de consulta y ordenación

Los contactos y las conversaciones se consultan únicamente dentro del proyecto asociado a las credenciales. La API devuelve todas las conversaciones normales asociadas al contacto en todas las bandejas de entrada del proyecto (conversation_category=chat), excluidas las conversaciones de tickets y sin filtrar por el agente actual, el responsable asignado ni la bandeja de entrada.

Se devuelven las conversaciones normales en todos los estados: open, resolved, pending, snoozed y closed. Esta API no permite filtrar por estado; aunque se proporcione status, los resultados no se restringen.

Los resultados se ordenan por fecha de creación de la conversación en orden descendente. Cuando las fechas de creación son iguales, se ordenan por la clave primaria interna de la conversación en orden descendente. El orden de paginación permanece estable mientras los datos no cambien. La paginación por páginas no garantiza una instantánea coherente mientras se crean o eliminan conversaciones simultáneamente.

Respuesta

Respuesta correcta

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

            

Parámetros de respuesta

Si el contacto no existe, no tiene conversaciones normales o la página solicitada supera el número total de páginas, se devuelve HTTP 200. En los tres casos, payload es un array vacío; meta.count conserva siempre el número total real de resultados.

La respuesta contiene únicamente los campos indicados anteriormente y no devuelve mensajes, archivos adjuntos ni información personal del contacto.

Respuesta de error

Las respuestas de error utilizan la siguiente estructura. Las descripciones de error no reproducen el valor de consulta:

              
              {
  "error": "Error description"
}

            

Notas de uso

• Esta API solo añade la función de consulta y no modifica los datos de contactos ni de conversaciones.
• La API no permite buscar contactos mediante coincidencias aproximadas. Asegúrese de que el identifier, la dirección de correo electrónico o el número de teléfono almacenados por el sistema externo coincidan con el atributo correspondiente del contacto en LiveDesk.
• Para procesar las conversaciones de los resultados de consulta, utilice payload[].id de la respuesta como ID externo de la conversación al llamar a las API V2 correspondientes.