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 project

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

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