Help Center

Explore our knowledge base
article

Export your conversations history using our API

1. Why would you need to export your conversations history ?

Thanks to the export of your conversations, you can collect your whole conversation history and then analyze their content or save them into your own database.

The aim of this article is to help you better understand the conversation model we are using.

 

2. Consume the conversation resource of our REST API

With the iAdvize REST API, you can choose to get a specific conversation by its ID or you can list your conversations using filters.

For example, if you need to get a specific conversation, you just need to pass it's ID in the URL like below: 

https://ha.iadvize.com/api/2/conversation/:conversationID
⚠️ Note that the API base url can be different depending the environment on which your customer account is linked to, check our documentation to learn more.

 

The result looks like this :
{
"meta": {
"status": "success"
},
"data": {
"id": 99993266,
"channel": "chat",
"history": "[2,\"2020-04-23 14:31:22\",\"Hello\"],[5,\"2020-04-23 14:31:23\",\"https://mywebsite.com"],[3,\"2020-04-23 14:31:33\",\"OPERATOR_CHAT_CLOSE\"]",
"history_link": "",
"operator_answered": false,
"operator_closed": true,
"waiting_list": false,
"page_type": "",
"created_at": "2020-04-23 14:31:22",
"closed_at": "2020-04-23 14:31:33",
"website_id": 9999,
"operator_id": 999079,
"skill_id": null,
"visitor_id": 99994522,
"visitor_uid": "7be1bdf63660b39...a14b5ea18a851ea98",
"tag_list": [
299029
],
"rule_id": 317996,
"xmpp_id": "bfd6dd11-4d13-xxxx-b438-dcc0649b4836",
"_link": "/conversation/99993266"
}
}

 

Furthermore, you can add some filters in the URL if, for instance, you want to list all the conversations for a specific project and on a specific timeframe like below:

 

https://ha.iadvize.com/api/2/conversation?filters[website_id]=xxx
&filters[from]=2020-04-03T00:00:00&filters[to]=2020-04-03T23:59:59

 

⚠️ Note that the filter on the dates is done on the "created_at" field and dates are stored in iAdvize servers using CEST Time zone.

 

Here is the result:

{
"meta": {
"status": "success",
"filters": [
"channel",
"from",
"to",
"website_id",
"operator_id",
"skill_id",
"tag_id",
"visitor_id",
"rule_id",
"skill_id",
"from_community"
]
},
"data": [
{
"id": 99993266,
"_link": "/conversation/99993266"
},
{
"id": 99999153,
"_link": "/conversation/99999153"
},
{
"id": 99992340,
"_link": "/conversation/99992340"
}
],
"pagination": {
"page": 1,
"pages": 1,
"limit": 20,
"count": 3
}
}


Good 👍!

But something tells me you would like more information than just the id and the conversation link 🤔... We can do this!

By adding in the URL the parameter full=1 you will get the details of the conversations. The new request will then look like this: 

https://ha.iadvize.com/api/2/conversation?filters[website_id]=xxx
&filters[from]=2020-04-23T00:00:00&filters[to]=2020-04-23T23:59:59&full=1

 

Perfect 👌

Now, the request returns a list of detailed conversations:

{
"meta": {
"status": "success",
"filters": [
"channel",
"from",
"to",
"website_id",
"operator_id",
"skill_id",
"tag_id",
"visitor_id",
"rule_id",
"skill_id",
"from_community"
]
},
"data": [
{
"id": 99993266,
"channel": "chat",
"history": "[2,\"2020-04-23 14:31:22\",\"Hello\"],[5,\"2020-04-23 14:31:23\",\"https://mywebsite.com"],[3,\"2020-04-23 14:31:33\",\"OPERATOR_CHAT_CLOSE\"]",
"history_link": "",
"operator_answered": false,
"operator_closed": true,
"waiting_list": false,
"page_type": "",
"created_at": "2020-04-23 14:31:22",
"closed_at": "2020-04-23 14:31:33",
"website_id": 9999,
"operator_id": 999079,
"skill_id": null,
"visitor_id": 99994522,
"visitor_uid": "7be1bdf63660b39...a14b5ea18a851ea98",
"tag_list": [
299029
],
"rule_id": 317996,
"xmpp_id": "bfd6dd11-4d13-xxxx-b438-dcc0649b4836",
"_link": "/conversation/99993266"
},
{...},
{...}
],
"pagination": {
"page": 1,
"pages": 1,
"limit": 20,
"count": 3
}
}


3. Understand the structure of the "history" field in the conversation resource

If we take a closer look at the details of the conversation, we can see that the history field contains the messages of the conversation. But this field seems to contain a structure in a large string.

The structure looks like JSON but in order to parse it we first have to add brackets around it.

The Javascript example below parses the string and transform it to a real JSON structure which is easier to manipulate: 

const myJSONHistory = JSON.parse('['+history+']');

 

Now the myJSONHistory variable contains an array of arrays like this: 

const myJSONHistory = [
  [5, "2020-04-23 10:07:24", "https://mywebsite.com"],
  [1, "2020-04-23 10:07:25", "Hello I am Ana, how can I help you ?"],
  [3, "2020-04-23 10:07:25", "The rule Chat is activated."],
  [2, "2020-04-23 10:07:35", "Hello I am John, I have a question product."],
  [2, "2020-04-23 10:07:49", "I am looking for this very specific product. "],
  [1, "2020-04-23 10:07:57", "Right we have it. "],
  [2, "2020-04-23 10:08:06", "Perfect, let me order it."],
  [1, "2020-04-23 10:08:18", "Have a nice day,"],
  [3, "2020-04-23 10:08:22", "VISITOR_CHAT_CLOSE"],
  [3, "2020-04-23 10:10:57", "OPERATOR_CHAT_CLOSE"]
];

 

Each nested array contains the following information by index: 

Index Description
0 ID that identify the source of the message or event
1 The event date (Datetime format)
2 Context of the event (operator or visitor message, technical code or some contextual informations)

 

For more information, do not hesitate to look at our developer documentation