GraphQL Customer API

ⓘ

Who can use this feature?

Available to all users on any plan.
You'll need your App ID and Secret key from Settings > API. See API overview for how to generate them.

Overview

The GraphQL Customer API gives you read access to the contacts Chatty has collected for your store — names, emails, channels, order counts, total spend, and chat activity. Use it to sync contacts into a CRM, push segments to an email tool, or build a custom dashboard.

It's a single GraphQL endpoint, so you ask for exactly the fields you need in one request.

Endpoint

POST https://graphql.chatty.net/graphql

All requests are POST with a JSON body containing your query (and optional variables).

Authentication

Every request needs two headers:

Header	Value
`x-api-id`	Your App ID (from Settings > API)
`x-api-secret`	Your Secret key (from Settings > API)

Keep your Secret key private — it authenticates as your store. Never expose it in front-end code or a public repository. If it leaks, rotate it from Settings > API (the old key stops working instantly).

Queries

`customer` — fetch one contact

Argument	Type	Required	Description
`id`	`ID!`	Yes	The Chatty customer ID.

`customers` — list contacts (paginated)

Relay-style cursor pagination. Use first/after to page forward, last/before to page backward.

Argument	Type	Description
`first`	`Int`	Number of records to return forward.
`after`	`String`	Cursor to start after.
`last`	`Int`	Number of records to return backward.
`before`	`String`	Cursor to end before.

Schema

`Customer`

Field	Type	Description
`id`	`ID!`	Chatty customer ID.
`shopId`	`String!`	Your store identifier.
`shopifyCustomerId`	`String`	Matching Shopify customer ID, if any.
`firstName`	`String!`	First name.
`lastName`	`String`	Last name.
`email`	`String`	Email address.
`phone`	`String`	Phone number.
`ipLocation`	`String`	Location derived from IP.
`ipAddress`	`String`	Last seen IP address.
`type`	`CustomerType!`	Contact type (see enum below).
`channels`	`[Channel!]!`	Channels the contact has used.
`ordersCount`	`Int!`	Number of orders placed.
`totalSpent`	`Float!`	Lifetime spend.
`createdAt`	`DateTime!`	When the contact was first seen.
`updatedAt`	`DateTime`	Last update timestamp.
`lastChatAt`	`DateTime`	Last time the contact chatted.
`fullName`	`String!`	Convenience full name.

Connection types

customers returns a CustomerConnection:

Type	Fields
`CustomerConnection`	`edges [CustomerEdge!]!`, `nodes [Customer!]!`, `pageInfo PageInfo!`, `totalCount Int!`
`CustomerEdge`	`cursor String!`, `node Customer!`
`PageInfo`	`hasNextPage Boolean!`, `hasPreviousPage Boolean!`, `startCursor String`, `endCursor String`

Enums

CustomerType — CUSTOMER, GUEST, ANONYMOUS

Channel — ONLINE_STORE, EMAIL, WHATSAPP, FACEBOOK, INSTAGRAM

Examples

List the first 50 contacts

query {
  customers(first: 50) {
    totalCount
    pageInfo { hasNextPage endCursor }
    nodes {
      id
      fullName
      email
      channels
      ordersCount
      totalSpent
      lastChatAt
    }
  }
}

Page to the next 50

query NextPage($after: String!) {
  customers(first: 50, after: $after) {
    pageInfo { hasNextPage endCursor }
    nodes { id email }
  }
}

Fetch a single contact

query {
  customer(id: "CUSTOMER_ID") {
    fullName
    email
    totalSpent
    ordersCount
  }
}

Call it with curl

curl -X POST https://graphql.chatty.net/graphql \
  -H "x-api-id: YOUR_APP_ID" \
  -H "x-api-secret: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ customers(first: 10) { nodes { id email totalSpent } } }"}'

Pagination

The API uses Relay-style cursor pagination. To walk the full list:

Request customers(first: N).
Read pageInfo.endCursor and pageInfo.hasNextPage.
While hasNextPage is true, request customers(first: N, after: endCursor).

Rate limiting

Requests are rate-limited with a token-bucket algorithm. Each response includes a cost breakdown under extensions.cost. If you're paginating large datasets, read the cost field and slow down when you're close to your limit.

Need help?

If you run into issues with your key or a query, contact the Chatty support team from your dashboard. For no-code options, see Klaviyo, Zendesk, or Joy.

Overview Chat Conversations API