Skip to main content

How to retrieve conversation histories via API

  • Updated
  1. Context
  2. Get all messages from a customer by a ticket
  3. Get last messages 
  4. Get logged messages 
  5. Technical documentation

 

Context

Currently, Blip has 3 different requests for retrieving conversation message histories through the API:

  1. Get all messages from a customer by a ticket: Returns all messages from a customer linked to a ticket over a period of up to 30 days.

  2. Get last messages: Returns the last 20 messages exchanged between the user, bot, and agent over a period of up to 90 days.

  3. Get logged messages: Returns the last 100 messages from your bot connected to WhatsApp over a period of up to 3 days.

Before you start

To run the queries, you must have your API key. You can obtain this key by following the instructions in the following official documentation: How do I find my bot's API KEY? 

 

Get all messages from a customer by a ticket

This request returns all messages from the customer responsible for the ticket. The response will not include only the messages exclusive to that ticket, but all messages received from and sent by the customer.

To structure this call, note the required and optional parameters:

  • Replace the {{ticketId}} variable with the exact ID of the ticket whose messages you want to retrieve.

  • The getFromOwnerIfTunnel parameter is required for this specific query.

  • By default, the value of getFromOwnerIfTunnel is false.

  • If you are using a router architecture, the value of getFromOwnerIfTunnel must be set to true.

  • If you are not using a router architecture, the parameter can be omitted from the request or explicitly set to false.

Request header

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

Request body:

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

Expected response

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

 

How do I find the ticket ID to use in this query?

There are two ways to find the ticket identifier to enter in the body of your request:

1. Through the Service History 

In the “Service” tab of the human service bot, find the “History” menu and look for the ticket. Then open the ticket history, and you will notice that the alphanumeric ID is in the browser URL:

2. Through the tickets API 

  1. Use the tickets API documented at https://docs.blip.ai/#get-all-tickets-of-a-bot.
  2. Apply the sequentialId filter.
  3. Use the following request body to search for the ID:

REQUEST BODY:

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

You will find the ID in the request response:

 

Get last messages

API key usage rules and response behavior:

  • If you use the API key directly from the human service bot, the request will return only the last 20 messages that occurred specifically in that bot.

  • If you use the router's API key, the request will return the last messages that occurred in the subbots and services linked to that router.

In addition, the value of the user_identity variable will vary depending on which API key was used.

Request header:

Method: POST

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

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}

Request body:

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

Expected response:

{
  "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"
  }
}

 

How do I find the user ID to use in this query?

The user_identity is the contact identifier and varies depending on the API key used. 

If the key belongs to the subbot, copy the contact ID directly from the Human Service bot, either from the history or the Contacts tab, as shown in the example below:

In the case of the router, locate the contact through the Contacts tab as well and use the corresponding ID, making sure that this value is different for each bot. As shown in the example below:

See the complete API documentation: https://docs.blip.ai/#get-last-messages 
 

Get logged messages

With this request, you can retrieve all of the last 100 messages that were logged in your bot connected to the WhatsApp channel.

Specific usage rules:

  • This request will return the last messages only if the API key used in the header belongs exclusively to the bot connected to WhatsApp.

  • If you use a router architecture, you must use the router's key.

  • This request supports the $skip filter, which must be used for pagination processes.

  • This request supports the $take filter, which can be used to limit the total number of items returned in the call. The maximum value allowed for the $take filter is 100 items.

Request header:

Request body:

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

Expected response:

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",
}

 

Technical documentation

Related articles