Chatty GraphQL API

GraphQL API for Chatty - a customer management and messaging platform by Avada.

Authentication

All API requests require authentication via headers:

x-api-id - Your API key ID
x-api-secret - Your API secret key

Rate Limiting

API requests are rate-limited using a token bucket algorithm. Each response includes cost information in the extensions.cost field.

Pagination

This API uses Relay-style cursor-based pagination. Use first/after for forward pagination and last/before for backward pagination.

Contact

Chatty

https://chatty.net/

API Endpoints

# Production:
https://graphql.chatty.net/graphql

Queries

`customer`

Description

Look up a single customer by their ID.

Response

Returns a Customer

Arguments

Name	Description
`id` - `ID!`	The ID of the customer.

Example

Query

query Customer($id: ID!) {
  customer(id: $id) {
    id
    shopId
    shopifyCustomerId
    firstName
    lastName
    email
    phone
    ipLocation
    ipAddress
    type
    channels
    ordersCount
    totalSpent
    createdAt
    updatedAt
    lastChatAt
    fullName
  }
}

Variables

{"id": "4"}

Response

{
  "data": {
    "customer": {
      "id": "4",
      "shopId": "xyz789",
      "shopifyCustomerId": "xyz789",
      "firstName": "abc123",
      "lastName": "abc123",
      "email": "xyz789",
      "phone": "abc123",
      "ipLocation": "abc123",
      "ipAddress": "abc123",
      "type": "CUSTOMER",
      "channels": ["ONLINE_STORE"],
      "ordersCount": 987,
      "totalSpent": 987.65,
      "createdAt": "2007-12-03T10:15:30Z",
      "updatedAt": "2007-12-03T10:15:30Z",
      "lastChatAt": "2007-12-03T10:15:30Z",
      "fullName": "xyz789"
    }
  }
}

Queries

`customers`

Description

Retrieve a paginated list of customers.

Response

Returns a CustomerConnection!

Arguments

Name	Description
`first` - `Int`	The first n elements from the paginated list.
`after` - `String`	The elements that come after the specified cursor.
`last` - `Int`	The last n elements from the paginated list.
`before` - `String`	The elements that come before the specified cursor.

Example

Query

query Customers(
  $first: Int,
  $after: String,
  $last: Int,
  $before: String
) {
  customers(
    first: $first,
    after: $after,
    last: $last,
    before: $before
  ) {
    edges {
      cursor
      node {
        ...CustomerFragment
      }
    }
    nodes {
      id
      shopId
      shopifyCustomerId
      firstName
      lastName
      email
      phone
      ipLocation
      ipAddress
      type
      channels
      ordersCount
      totalSpent
      createdAt
      updatedAt
      lastChatAt
      fullName
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Variables

{
  "first": 987,
  "after": "abc123",
  "last": 123,
  "before": "abc123"
}

Response

{
  "data": {
    "customers": {
      "edges": [CustomerEdge],
      "nodes": [Customer],
      "pageInfo": PageInfo,
      "totalCount": 123
    }
  }
}

Types

Boolean

Description

The Boolean scalar type represents true or false.

Types

Channel

Description

A communication channel through which a customer interacts.

Values

Enum Value	Description
`ONLINE_STORE`	The online storefront.
`EMAIL`	Email communication.
`WHATSAPP`	WhatsApp messaging.
`FACEBOOK`	Facebook messaging.
`INSTAGRAM`	Instagram messaging.

Example

"ONLINE_STORE"

Types

Customer

Description

A customer who interacts with the shop.

Fields

Field Name	Description
`id` - `ID!`	Unique identifier of the customer.
`shopId` - `String!`	The ID of the shop this customer belongs to.
`shopifyCustomerId` - `String`	The corresponding Shopify customer ID, if linked.
`firstName` - `String!`	The customer's first name, defaults to an empty string if not set.
`lastName` - `String`	The customer's last name.
`email` - `String`	The customer's email address.
`phone` - `String`	The customer's phone number.
`ipLocation` - `String`	The geographic location inferred from the IP address.
`ipAddress` - `String`	The customer's most recent IP address.
`type` - `CustomerType!`	The classification type of the customer, defaults to CUSTOMER.
`channels` - `[Channel!]!`	The communication channels the customer has used, defaults to ONLINE_STORE.
`ordersCount` - `Int!`	The total number of orders placed by the customer.
`totalSpent` - `Float!`	The total amount the customer has spent.
`createdAt` - `DateTime!`	When the customer was created.
`updatedAt` - `DateTime`	When the customer was last updated.
`lastChatAt` - `DateTime`	When the customer last sent a chat message.
`fullName` - `String!`	The customer's full name (first + last).

Example

{
  "id": 4,
  "shopId": "abc123",
  "shopifyCustomerId": "xyz789",
  "firstName": "abc123",
  "lastName": "xyz789",
  "email": "xyz789",
  "phone": "abc123",
  "ipLocation": "xyz789",
  "ipAddress": "abc123",
  "type": "CUSTOMER",
  "channels": ["ONLINE_STORE"],
  "ordersCount": 987,
  "totalSpent": 123.45,
  "createdAt": "2007-12-03T10:15:30Z",
  "updatedAt": "2007-12-03T10:15:30Z",
  "lastChatAt": "2007-12-03T10:15:30Z",
  "fullName": "abc123"
}

Types

CustomerConnection

Fields

Field Name	Description
`edges` - `[CustomerEdge!]!`	The connection between the node and its parent. Each edge contains a minimum of the edge's cursor and the node.
`nodes` - `[Customer!]!`	A list of nodes that are contained in CustomerEdge.
`pageInfo` - `PageInfo!`	An object that is used to retrieve cursor information about the current page.
`totalCount` - `Int!`	The total number of items in the connection.

Example

{
  "edges": [CustomerEdge],
  "nodes": [Customer],
  "pageInfo": PageInfo,
  "totalCount": 123
}

Types

CustomerEdge

Fields

Field Name	Description
`cursor` - `String!`	The position of each node in an array, used in pagination.
`node` - `Customer!`	The item at the end of CustomerEdge.

Example

{
  "cursor": "xyz789",
  "node": Customer
}

Types

CustomerType

Description

The classification type of a customer.

Values

Enum Value	Description
`CUSTOMER`	A registered customer with an account.
`GUEST`	A guest who has not created an account.
`ANONYMOUS`	An unidentified visitor.

Example

"CUSTOMER"

Types

DateTime

Description

A date-time string at UTC, such as 2019-12-03T09:54:33Z, compliant with the date-time format.

Example

"2007-12-03T10:15:30Z"

Types

Float

Description

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example

987.65

Types

ID

Description

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Example

Types

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example

Types

PageInfo

Fields

Field Name	Description
`hasNextPage` - `Boolean!`	Whether there are more pages to fetch following the current page.
`hasPreviousPage` - `Boolean!`	Whether there are more pages to fetch before the current page.
`startCursor` - `String`	The cursor corresponding to the first node in edges.
`endCursor` - `String`	The cursor corresponding to the last node in edges.

Example

{
  "hasNextPage": false,
  "hasPreviousPage": true,
  "startCursor": "xyz789",
  "endCursor": "xyz789"
}

Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example

"xyz789"

Documentation by Anvil SpectaQL