1. What data can you retrieve?
iAdvize provides a GraphQL API to retrieve conversations data. Here is an example of the data you can find in the searchClosedConversation resource:
- Duration of the conversation, the start date and end date
- Tags associated to the conversation
- The channel of the conversation (Chat, Call, Video, etc)
- Transactions made through the conversation
- The satisfaction data (CSAT, NPS)
To see all the data available, you can click on this link.
2. How to use our GraphQL API?
2.1. Authentication
2.1.1 Get an access token
If you want to use our GraphQL API, you first need to get an access token.
Authentication uses temporary & revocable access tokens. You can generate your own access token with the following HTTP request:
cURL example:
curl --request POST \ --url 'https://api.iadvize.com/oauth2/token' \ --data 'username=YOUR_EMAIL&password=YOUR_PASSWORD&grant_type=password'
NodeJS example:
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://api.iadvize.com/oauth2/token',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
form: {
'username': 'YOUR_EMAIL',
'password': 'YOUR_PASSWORD',
'grant_type': 'password'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
| ⚠️ Note that you must set application/x-www-form-urlencoded in the Content-Type header |
2.1.2 Authenticate each of your API calls
To authenticate an API call, you just need to pass the access token in an authorization header like the following examples:
cURL example:
curl --location --request POST 'https://api.iadvize.com/graphql' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"YOUR_GRAPHQL_QUERY","variables":{...}}'
NodeJS example:
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://api.iadvize.com/graphql',
'headers': {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'YOUR_GRAPHQL_QUERY',
variables: {...}
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
| ⚠️ Note that you must set application/json in Content-Type header |
For more information about authentication in GraphQL, you can read our developer documentation
2.2. How to fetch conversations data?
Once you get an access token and now you know how to use it to authenticate your request, you can now make a GraphQL request to get some conversation data.
One of the advantages of GraphQL is that you can retrieve multiple nested resources via a single query, we will see this in different examples below.
Before going any further, we advise you to take a look at our GraphiQL tool which allows you to access all the resources, their fields and the search filters you can use.
https://developers.iadvize.com/tools/graphiql
2.2.1. Get conversation start & end date and duration
In the example below, we are fetching all closed conversation on a specified date range and for a specific projectquery MyQuery {
searchClosedConversations(
filters: {projectIds: 9999},
interval: {from: "2020-06-01T00:00:00Z", to: "2020-06-02T00:00:00Z"}
) {
edges {
node {
conversation {
id
duration
createdAt
closedAt
}
}
}
}
}
2.2.2. Add satisfaction to the previous request
As GraphQL allows to include nested resources. In this example we add to the previous query the satisfaction data.
query MyQuery {
searchClosedConversations(
filters: {projectIds: 9999},
interval: {from: "2020-06-01T00:00:00Z", to: "2020-06-02T00:00:00Z"}
) {
edges {
node {
conversation {
id
duration
createdAt
closedAt
},
satisfactionSurvey {
comment
customerSatisfaction
netPromoterScore
}
}
}
}
}
2.2.3. Add conversions data
Like the previous example we can add the conversion data to the request like the example below:
query MyQuery {
searchClosedConversations(
filters: {projectIds: 9999},
interval: {from: "2020-06-01T00:00:00Z", to: "2020-06-02T00:00:00Z"}
) {
edges {
node {
conversation {
id
duration
createdAt
closedAt
},
satisfactionSurvey {
comment
customerSatisfaction
netPromoterScore
},
conversions {
transactions {
amount
currency
externalConversionId
receivedAt
}
}
}
}
}
}