GraphQL API

Attentive's API now supports GraphQL to enable developers to integrate with the Attentive platform. This API is in beta - the current set of fields in the Graph is equivalent to our Attentive API and we plan to expand our GraphQL API. Attentive intends for GraphQL to become the primary query language for its API. Please note that the schema may experience some changes over time.

For the time being, all supported functionality in the Graph is documented in this section.

Further information about GraphQL is available here.

Authentication

All GraphQL API queries require a valid Attentive application token. These are the same tokens used by the REST API. A token can be obtained in two ways, either using a Private App or a Public App. If you want to call the API on behalf of only your company, a Private App is likely the best option. See more details about Authentication at Attentive here.

Also note that fields and mutations on the Graph are tied to access scopes. Scopes are assigned to private apps when they are created and during the install flow for public apps. The access token in a request must have all access scopes required by the requested fields or mutations.

Graph queries

GraphQL queries are executed by sending POST HTTP requests to the endpoint:

POST https://api.attentivemobile.com/v1/graphql

Read requests always begin at the query root, whereas write requests always begin at the mutation root.

For example, this query provides information about the caller's access token, similar to the /me endpoint:

query {
  viewer {
    installedApplication {
      name
      installerCompany {
        name
      }
    }
  }
}

Status and error codes

Like REST, GraphQL queries return HTTP status codes. However, an important distinction is that the GraphQL API can return a 200 OK response code in cases that would typically produce 4xx or 5xx errors in REST. If there was an error in a query, the errors object in the response will be present and contain additional detail to help you debug.

For example, if a query requested a non-existent field in the Graph, the response would have a 200 OK status code, along with error details:

{
    "data": null,
    "errors": [
        {
            "message": "Validation error of type FieldUndefined: Field 'abc' in type 'installerCompany' is undefined",
            "locations": [
                {
                    "line": 3,
                    "column": 1
                }
            ],
            "extensions": {
                "classification": "ValidationError"
            }
        }
    ]
}

4xx and 5xx status codes will only be returned in the case of authorization (401 Unauthorized) or malformed requests.