Developer platform

GraphQL API

Getting started on GraphQL

GraphQL is our new API, all new resources will only be exposed in this new API. We are currently migrating old resources from Rest API to GraphQL. Please note that we are in alpha version, resources are pretty stable but authentication method will change in the next months.

One of the power of GraphQL API is to allow you retrieve many resources in one HTTP call. You can request only fields you need. If you wan to learn more about GraphQL, please check Learn GraphQL

Authentication

Authentication uses temporary & revocable access tokens. You can generate an access token by calling the url below with a user email & password.

POST /oauth2/token Parameters (sent as application/x-www-form-urlencoded)

ParameterDescriptionValuesMandatory
usernameUser emailStringYes
passwordUser passwordStringYes
grant_typeOauth2 grant type (only password is supported)StringYes
{
    "refresh_token": "***************************",
    "token_type": "bearer",
    "expires_in": 86400,
    "access_token": "***************************"
}
    curl -XPOST https://api.iadvize.com/oauth2/token -d "username={EMAIL}&password={PASSWORD}&grant_type=password"

To authenticate an API call just pass the access token in an authorization header. You can verify token validity with the authenticated route below.

    curl -H "Authorization: Bearer {ACCESS_TOKEN}" https://api.iadvize.com/_authenticated

Resources

Documentation GraphQL

Examples

To use the GraphQL API, call the URL below with the Authorization header containing your access token.

POST /graphql

Parameters (sent as application/json)

ParameterDescriptionValuesMandatory
queryGraphQL queryStringYes
variablesVariables to be used in the GraphQL queryStringNo
operationNameOperation to perform if the GraphQL query contains several operationsStringNo

Complete example

You can sent this kind of payload directly from a HTTP client to https://api.iadvize.com/graphql.

{
  "query": "query GetConnector($connectorId: UUID!) { connector(id: $connectorId) { name } }",
  "variables": {

"connectorId": "41c64064-4729-4d83-a939-8d46ac06d207"

} }

Following examples describe uniquely the graphQL query (that has to be serialized into the JSON)

Connectors

GraphQL query example

query {
    GetConnector(41c64064-4729-4d83-a939-8d46ac06d207: UUID!) {
        connector(id: 41c64064-4729-4d83-a939-8d46ac06d207) { name }
    }
}

Result

{
  "data": {
    "connector": {
      "name": "..."
    }
  }
}

Satisfaction survey responses

GraphQL query example

query {
    satisfactionSurveyResponses(
        projectIds: [1,2], 
        interval: {
	    from: "2019-01-04T00:00:00+01:00",
	    to: "2019-01-04T23:59:59+01:00"
        }
    ) {
    edges {
      node {
        customerSatisfaction,
        netPromoterScore,
        satisfactionComment,
        conversation {
          id,
          createdAt,
          closedAt,
          project {
            id,
            name,
          },
          agents {
            id,
            firstName,
            lastName,
            __typename
          }
        }
      }
    },
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Get the 100 first responses to the satisfaction survey during the given time interval.

ParameterDescriptionValuesMandatory
intervalFilter responses on this time interval between 'from' and 'to' using ISO 8601 formatObjectYes
interval.fromTime interval startISO 8601 Date as StringYes
interval.toTime interval endISO 8601 Date as StringYes
projectIdsFilter responses on project idArray of IntegerNo
cursor'endCursor' of the previous request to get the next 100 responsesStringNo

Result

{
        "data": {
          "satisfactionSurveyResponses": {
            "edges": [
              {
                "node": {
                  "customerSatisfaction": 5,
                  "netPromoterScore": 10,
                  "satisfactionComment": "Rapide",
                  "conversation": {
                    "id" : "d42d8291-6542-4eed-bb44-988e5264fc2d",
                    "createdAt": "2019-01-04T11:12:13Z",
                    "closedAt": "2019-01-04T12:13:14Z",
                    "project": {
                      "id": 1,
                      "name": "My brand online"
                    },
                    "agents": [
                      {
                        "id": 30,
                        "firstName": null,
                        "lastName": "Wall-e",
                        "type": "bot"
                      },
                      {
                        "id": 31,
                        "firstName": "Jean",
                        "lastName": "Robert",
                        "__typename": "Expert"
                      }
                    ]
                  }
                }
              }
            ],
            "pageInfo": {
              "endCursor": "MTU0NjU5NzY5MjAwMCYmMmVhMTYyZjgtNTlkZC00MzkxLTljNTMtMmJkNjM2YzFlNWU1",
              "hasNextPage": true
            }
          }
        }
      }
Satisfaction survey fieldsDescriptionValuesMandatory
customerSatisfactionresponse to the customer satisfaction questionInteger 1 to 5Yes
netPromoterScoreresponse to the net promoter questionInteger 0 to 10No
satisfactionCommentresponse to the comment questionStringNo
conversationconversation preceding to the surveyConversationYes
Conversation fieldsDescriptionValuesMandatory
idconversation unique idStringYes
createdAtdate when the conversation was initiatedISO 8601 Date as StringYes
closedAtdate when the agent closed the conversationISO 8601 Date as StringYes
projectproject of the conversationProjectYes
agentslist of agents which participated to the conversationArray of AgentYes
Project fieldDescriptionValuesMandatory
idproject unique idIntegerYes
nameproject nameStringYes
Agent fieldDescriptionValuesMandatory
idagent unique idIntegerYes
firstNameagent first nameStringNo
lastNameagent last nameStringYes
__typenameuser typeString (Expert, Bot, Professional)Yes
Page info fieldDescriptionValuesMandatory
endCursorcursor to fetch the next page of responsesStringNo
hasNextPagetrue if there is more responsesBooleanYes