Saltar al contenido principal

Cómo obtener historiales de conversaciones mediante la API

  • Actualización
  1. Contexto
  2. Get all messages from a customer by a ticket
  3. Get last messages 
  4. Get logged messages 
  5. Documentación técnica

 

Contexto

Actualmente, Blip cuenta con 3 solicitudes diferentes para obtener el historial de mensajes de conversaciones mediante la API:

  1. Get all messages from a customer by a ticket: Devuelve todos los mensajes de un cliente vinculados a un ticket durante un periodo de hasta 30 días.

  2. Get last messages: Devuelve los últimos 20 mensajes intercambiados entre el usuario, el bot y el agente durante un periodo de hasta 90 días.

  3. Get logged messages: Devuelve los últimos 100 mensajes de tu bot conectado a WhatsApp durante un periodo de hasta 3 días.

Antes de comenzar

Para ejecutar las consultas, es obligatorio contar con tu API-Key. Puedes obtener esta clave siguiendo las instrucciones de la siguiente documentación oficial: ¿Cómo encontrar la API-KEY de mi bot? 

 

Get all messages from a customer by a ticket

Esta solicitud se encarga de devolver todos los mensajes del cliente responsable del ticket. La respuesta no incluirá únicamente los mensajes exclusivos de ese ticket, sino todos los mensajes que el cliente haya recibido y enviado.

Para estructurar esta llamada, consulta los parámetros obligatorios y opcionales:

  • Reemplaza la variable {{ticketId}} por el ID exacto del ticket cuyos mensajes deseas obtener.

  • El parámetro getFromOwnerIfTunnel es obligatorio para esta consulta específica.

  • De forma predeterminada, el valor de getFromOwnerIfTunnel es false.

  • Si utilizas una estructura de enrutador, el valor de getFromOwnerIfTunnel debe definirse obligatoriamente como true.

  • Si no utilizas una estructura de enrutador, puedes omitir el parámetro en la solicitud o definirlo explícitamente como false.

Encabezado de la solicitud

  • Método: POST
  • URI: https://{{contract_id}}.http.msging.net/commands
  • Content-Type: application/json
  • Authorization: Key {YOUR_TOKEN}

Cuerpo de la solicitud:

{ 
    "id": "{{$guid}}", 
    "to": "postmaster@desk.msging.net", 
    "method": "get", 
    "uri": "/tickets/{{ticketId}}/messages?$take=5&getFromOwnerIfTunnel=true" 
}

Respuesta esperada

HTTP/1.1 200 OK

Content-Type: application/json

{
    "type": "application/vnd.lime.collection+json",
    "resource": {
        "total": 3,
        "itemType": "application/vnd.iris.thread-message+json",
        "items": [
            {
                "id": "d7278f36a074e0",
                "direction": "sent",
                "type": "text/plain",
                "content": "937dec5c1a27.demobot@0mn.io",
                "date": "2019-12-04T16:15:34.759Z",
                "status": "dispatched"
            },
            {
                "id": "289ae91a-ff6e-47c1-be72-c41d6a46ff0f",
                "direction": "sent",
                "type": "application/vnd.lime.redirect+json",
                "content": {},
                "date": "2019-12-04T16:15:33.746Z",
                "status": "dispatched"
            },
            {
                "id": "fwd:fwd:b0534f19-d607-4ac9-b6bc-ac191f5aecf7",
                "direction": "sent",
                "type": "text/plain",
                "content": "oi",
                "date": "2019-12-04T16:14:51.952Z",
                "status": "dispatched"
            }
        ]
    },
    "method": "get",
    "status": "success",
    "id": "0ae73314-86d9-4dc0-823d-cfad6636d829",
    "from": "postmaster@desk.msging.net/#az-iris7",
    "to": "demobot@msging.net"
}

 

¿Cómo encontrar el ID del ticket para utilizarlo en esta consulta?

Existen dos formas de encontrar el identificador del ticket que debes ingresar en el cuerpo de tu solicitud:

1. A través del Historial de atenciones 

En la pestaña “Atención” del bot de atención humana, encuentra el menú “Historial” y busca el ticket. Después, abre el historial del ticket y notarás que el ID alfanumérico se encuentra en la URL del navegador:

2. A través de la API de tickets 

  1. Utiliza la API de tickets documentada en https://docs.blip.ai/#get-all-tickets-of-a-bot.
  2. Aplica el filtro de sequentialId.
  3. Utiliza el siguiente cuerpo de solicitud para buscar el ID:

CUERPO DE LA SOLICITUD:

{
"id": "{{$guid}}",
"to": "postmaster@desk.msging.net",
"method": "get",
"uri": "/tickets?$filter=sequentialId%20eq%20{{sequentialId}}"
}

Encontrarás el ID en la respuesta de la solicitud:

 

Get last messages

Reglas de uso de la API-Key y comportamiento de la respuesta:

  • Si utilizas la API-Key directamente del bot de atención humana, la solicitud devolverá únicamente los últimos 20 mensajes que ocurrieron específicamente en ese bot.

  • Si utilizas la API-Key del enrutador, la solicitud devolverá los últimos mensajes que ocurrieron en los subbots y servicios vinculados a ese enrutador.

Además, el valor de la variable user_identity variará según la API-Key utilizada.

Encabezado de la solicitud:

Método: POST

URI: https://{{contract_id}}.http.msging.net/commands

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}

Cuerpo de la solicitud:

{
  "id":"{{$guid}}",
  "method":"get",
  "uri": "/threads/{{user_identity}}?refreshExpiredMedia=true"
}

Respuesta esperada:

{
  "type": "application/vnd.lime.collection+json",
  "resource": {
    "total": 3,
    "itemType": "application/vnd.iris.thread-message+json",
    "items": [
      {
        "id": "39ed84b9-f89e-4090-a27e-6bd1e69bdfef",
        "direction": "sent",
        "type": "text/plain",
        "content": "Welcome!",
        "date": "2016-12-06T12:32:44.799Z",
        "status": "consumed"
      },
      {
        "id": "15073ef5-9bab-493c-b630-8636eacba33e",
        "direction": "sent",
        "type": "text/plain",
        "content": "This is a test chatbot.",
        "date": "2016-12-06T12:32:40.640Z",
        "status": "consumed"
      },
      {
        "id": "9b49a7d6-d025-4bb6-a370-1d48fb457deb",
        "direction": "received",
        "type": "text/plain",
        "content": "Good morning",
        "date": "2016-12-06T12:32:35.398Z",
        "status": "accepted"
      }
    ]
  },
  "method": "get",
  "status": "success",
  "id": "0094447a-2581-4597-be6a-a5dff33af156",
  "from": "postmaster@msging.net/#az-iris1",
  "to": "contact@msging.net",
  "metadata": {
      "#command.uri": "lime://contact@msging.net/threads/destination@0mn.io"
  }
}

 

¿Cómo encontrar el ID del usuario para utilizarlo en esta consulta?

El user_identity es el identificador del contacto y varía según la API-Key utilizada. 

Si la key es del subbot, copia el ID del contacto directamente en el bot de Atención Humana, ya sea desde el historial o desde la pestaña Contactos, como se muestra en el ejemplo siguiente:

En el caso del enrutador, localiza también el contacto desde la pestaña Contactos y utiliza el ID correspondiente, asegurándote de que este valor sea diferente para cada bot. Como se muestra en el ejemplo siguiente:

Consulta la documentación completa de la API: https://docs.blip.ai/#get-last-messages 
 

Get logged messages

Con esta solicitud, puedes obtener los últimos 100 mensajes registrados en tu bot conectado al canal de WhatsApp.

Reglas específicas de uso:

  • Esta solicitud solo devolverá los últimos mensajes si la API-Key utilizada en el encabezado pertenece exclusivamente al bot conectado a WhatsApp.

  • Si utilizas una arquitectura de enrutadores, es obligatorio utilizar la Key del enrutador.

  • Esta solicitud admite el filtro $skip, que debe utilizarse para realizar procesos de paginación.

  • Esta solicitud admite el filtro $take, que puede utilizarse para limitar el total de elementos devueltos en la llamada. El valor máximo permitido para el filtro $take es de 100 elementos.

Encabezado de la solicitud:

Cuerpo de la solicitud:

{
  "to": "postmaster@msging.net",
  "method":"get",
  "uri": "/messages"
}

Respuesta esperada:

HTTP/1.1 200 OK

Content-Type: application/json

{
    "type": "application/vnd.lime.collection+json",
    "resource": {
        "total": 2,
        "itemType": "application/vnd.lime.message+json",
        "items": [
            {
                "type": "text/plain",
                "content": "Example",
                "id": "b2fea46b-a006-49e2-82fc-2e61e7832757",
                "from": "demobot@msging.net",
                "pp": "distList/demobot%40msging.net",
                "to": "2624285677641447@messenger.gw.msging.net",
                "metadata": {
                    "#messagePurpose": "CONFIRMED_EVENT_REMINDER",
                    "#scheduler.when": "11/26/2019 18:21:22",
                    "#message.replaceVariables": "True",
                    "#messageKind": "Active",
                    "#channel.preserveClaims": "True",
                    "#envelope.storageDate": "2019-11-26T18:21:27.000Z"
                }
            },
            {
                "type": "text/plain",
                "content": "Nice!!",
                "id": "b2fea46b-a006-49e2-82fc-2e61e7832757",
                "from": "demobot@msging.net",
                "pp": "postmaster/demobot%40msging.net",
                "to": "distList@broadcast.msging.net",
                "metadata": {
                    "#messagePurpose": "CONFIRMED_EVENT_REMINDER",
                    "#scheduler.when": "11/26/2019 18:21:22",
                    "#envelope.storageDate": "2019-11-26T18:21:27.000Z"
                }
            }
        ]
    },
    "method": "get",
    "status": "success",
    "id": "1b411af6-5057-4e9a-bd7e-4ec70b253b7e",
    "from": "postmaster@msging.net/#az-iris6",
    "to": "demobo4@msging.net",
}

 

Documentación técnica

Artículos relacionados