Pular para o conteúdo principal

Como obter históricos de conversas via API

  • Atualizado
  1. Contexto
  2. Get all messages from a customer by a ticket
  3. Get last messages 
  4. Get logged messages 
  5. Documentações técnicas

 

Contexto

Atualmente, a Blip possui 3 requisições diferentes para a obtenção do histórico de mensagens de conversas através da API:

  1. Get all messages from a customer by a ticket: Retorna todas as mensagens de um cliente vinculadas a um ticket num período de até 30 dias.

  2. Get last messages: Retorna as últimas 20 mensagens que foram trocadas entre o usuário, o bot e o atendente num período de até 90 dias.

  3. Get logged messages: Retorna as últimas 100 mensagens do seu bot que está conectado ao WhatsApp num período de até 3 dias.

Antes de começar

Para executar as consultas, é obrigatório possuir a sua API-Key. Você pode obter esta chave seguindo as instruções presentes na seguinte documentação oficial: Como encontrar a API-KEY do meu bot? 

 

Get all messages from a customer by a ticket

Esta requisição é responsável por retornar todas as mensagens do cliente que é o responsável pelo ticket. O retorno não incluirá apenas as mensagens exclusivas daquele ticket, mas todas as mensagens que foram recebidas e enviadas pelo cliente.

Para estruturar esta chamada, observe os parâmetros obrigatórios e opcionais:

  • Substitua a variável {{ticketId}} pelo ID exato do ticket cujas mensagens você deseja obter.

  • O parâmetro getFromOwnerIfTunnel é obrigatório para esta consulta específica.

  • Por padrão, o valor de getFromOwnerIfTunnel é false.

  • Caso você esteja utilizando uma estrutura de roteador, o valor de getFromOwnerIfTunnel deve obrigatoriamente ser definido como true.

  • Se não estiver em estrutura de roteador, o parâmetro pode ser omitido na requisição ou definido explicitamente como false.

Cabeçalho da requisição

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

Corpo da requisição:

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

Retorno esperado

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

 

Como encontrar o ID do ticket para utilizar nesta consulta?

Existem duas formas de encontrar o identificador do ticket para preencher no corpo da sua requisição:

1. Através do Histórico de Atendimentos 

Na aba “Atendimento” do bot de atendimento humano, encontre o menu “Histórico” e procure pelo ticket. Em seguida, abra o histórico do ticket e você notará que o id alfanumérico se encontra na URL do navegador:

2. Através da API de tickets 

  1. Utilize a API de tickets documentada em https://docs.blip.ai/#get-all-tickets-of-a-bot.
  2. Aplique o filtro de sequentialId.
  3. Utilize o seguinte corpo de requisição para buscar o ID:

CORPO DA REQUISIÇÃO:

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

Você encontrará o id no retorno da requisição:

 

Get last messages

Regras de uso da API-Key e comportamento do retorno:

  • Caso você utilize a API-Key diretamente do bot de atendimento humano, a requisição retornará somente as últimas 20 mensagens que ocorreram especificamente neste bot.

  • Caso você utilize a API-Key do roteador, a requisição retornará as últimas mensagens que ocorreram nos subbots e serviços que estão vinculados a este roteador.

Além disso, o valor da variável user_identity sofrerá variações dependendo de qual API-Key foi utilizada.

Cabeçalho da requisição:

Método: POST

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

Content-Type: application/json

Authorization: Key {YOUR_TOKEN}

Corpo da requisição:

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

Retorno esperado:

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

 

Como encontrar o ID do usuário para utilizar nessa consulta?

O user_identity é o identificador do contato e sofre variações dependendo da API-Key utilizada. 

Se a key for do subbot, copie o ID do contato diretamente no bot de Atendimento Humano, seja pelo histórico ou pela aba Contatos, conforme o exemplo abaixo:

No caso do roteador, localize o contato também pela aba Contatos e utilize o ID correspondente, atestando-se de que este valor é diferente para cada bot. Conforme o exemplo abaixo:

Consulte a documentação completa da API: https://docs.blip.ai/#get-last-messages 
 

Get logged messages

Com esta requisição, você pode obter todas as últimas 100 mensagens que foram registradas em seu bot conectado ao canal do WhatsApp.

Regras específicas de uso:

  • Esta requisição só irá retornar as últimas mensagens caso a API-Key utilizada no cabeçalho seja exclusivamente a do bot que está conectado ao WhatsApp.

  • Caso você utilize a arquitetura de roteadores, é obrigatório utilizar a Key do roteador.

  • Esta requisição possui suporte ao filtro $skip, que deve ser utilizado para realizar processos de paginação.

  • Esta requisição possui suporte ao filtro $take, que pode ser utilizado para limitar o total de itens que serão devolvidos na chamada. O valor máximo permitido para o filtro $take é de 100 itens.

Cabeçalho da requisição:

Corpo da requisição:

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

Retorno esperado:

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

 

Documentações técnicas

Artigos relacionados