Query the GraphQL surface

The REST API maps one endpoint to one resource: fetch a contact, then fetch its conversations, then fetch each conversation’s messages. The developer GraphQL surface is the shaped-read counterpart — you describe the tree you want, and one request returns a contact with its conversations and messages already nested, or a segment with its contacts pulled in a single round-trip. The surface is read-only and deliberately small. It covers the four highest-traffic CPaaS/CDP resource types — contacts, conversations, messages, and segments — so resolution-shaped reads stop needing client-side joins. For everything else (sending messages, managing channels, mutating anything), use the REST API.

When to use GraphQL vs REST

Situation	Reach for
Fetch a contact plus its conversations and messages in one call	GraphQL `contact`
List a segment’s contacts without a second lookup	GraphQL `segments`
Browse contacts or conversations with a lifecycle/status filter	GraphQL `contacts` / `conversations`
Send a message, update a contact, manage any resource	REST per-resource endpoint
Bulk export of a whole collection	REST list endpoints with pagination

Auth & roles

The GraphQL endpoints sit behind the same guard as every other developer route: authenticate with an API key (X-API-Key: dv_live_sk_…) or a dashboard session, and the calling key or session must carry an owner, admin, or developer role. See Authentication.

Your first request

The query endpoint is POST /api/v1/developer/graphql, with a { "query", "variables?", "operationName?" } JSON body. This query fetches one contact with its conversations and each conversation’s recent messages in a single round-trip:

curl -X POST https://api.orbit.devotel.io/api/v1/developer/graphql \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ContactExport($id: ID!, $conversationLimit: Int) { contact(id: $id) { id displayName phone email lifecycleStage conversations(limit: $conversationLimit) { id channel status lastMessageAt messages(limit: 20) { id direction body status sentAt } } } }",
    "variables": { "id": "contact_01JABC...", "conversationLimit": 10 },
    "operationName": "ContactExport"
  }'

The same call with the Node SDK’s underlying fetch:

const response = await fetch(
  "https://api.orbit.devotel.io/api/v1/developer/graphql",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY ?? "",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `
        query ContactExport($id: ID!) {
          contact(id: $id) {
            id
            displayName
            conversations(limit: 10) {
              id
              channel
              messages(limit: 20) { id direction body status }
            }
          }
        }
      `,
      variables: { id: "contact_01JABC..." },
      operationName: "ContactExport",
    }),
  },
);
const { data, errors } = await response.json();
if (errors) throw new Error(errors.map((e: { message: string }) => e.message).join("; "));

Always check the errors array. Per GraphQL-over-HTTP convention a query that parses but fails during execution still returns 200 OK with data: null (or partial data) and an errors list — it does not come back as a REST-style error envelope.

Schema introspection

The full schema is published as an SDL document, served alongside the OpenAPI spec, AsyncAPI contract, and Postman collection:

curl https://api.orbit.devotel.io/api/v1/developer/graphql/schema

It renders these types — Query with entry points contact, contacts, conversation, conversations, and segments, plus Contact, Conversation, Message, and Segment:

"""Read-only entry points over the highest-traffic CPaaS/CDP resources."""
type Query {
  """Fetch a single contact by its id."""
  contact(id: ID!): Contact
  """List contacts, most recently created first."""
  contacts(limit: Int, offset: Int, lifecycleStage: String): [Contact]
  """List conversations, most recently active first."""
  conversations(limit: Int, offset: Int, status: String): [Conversation]
  """List contact segments, most recently created first."""
  segments(limit: Int, offset: Int): [Segment]
}

"""A CDP contact profile."""
type Contact {
  id: ID
  displayName: String
  phone: String
  email: String
  lifecycleStage: String
  """This contact's conversations, most recently active first."""
  conversations(limit: Int): [Conversation]
  """This contact's messages, most recent first."""
  messages(limit: Int): [Message]
}

The SDL is rendered from the same descriptor that drives execution, so what you download is what the server enforces. Pin requests against the downloaded SDL — a field that isn’t in the schema is rejected, so no request can silently start returning a renamed shape.

The surface runs on a deliberately minimal query language: a single query operation, variables with defaults, field arguments, nested selection sets, and aliases. Mutations, subscriptions, fragments, directives, and __schema introspection are not supported — the SDL endpoint above is the schema contract.

Variables, operation names, and limits

query — the GraphQL document string, capped at 20 KB.
variables — a JSON object of values referenced as $name in the query. Variable definitions in the query can declare defaults; a request-supplied value overrides the default.
operationName — required when the document contains more than one operation. If it names an operation that isn’t in the document, you get Unknown operation named "…" in errors.

Two static guards bound the work a query can trigger, checked before anything executes:

Depth cap — a selection set nested more than 8 levels is rejected.
Complexity cap — each resolver-backed field costs one unit, and every list field multiplies everything beneath it by its (bounded) page size; a selection set estimated over 1000 units is rejected with Query is too complex: …. Reduce nesting, lower the limit arguments, or drop repeated aliased subtrees.

Both guards return the standard GraphQL envelope — 200 OK with { "data": null, "errors": [{ "message": "…" }] }. Inspector responses carry Cache-Control: no-store and are never cached.

Prototype in the dashboard Explorer

Before wiring code, open Developer → GraphQL in the dashboard. The Explorer runs queries against your live tenant with your session, renders the schema next to the editor, and shows the exact data/errors envelope your code would receive. Iterate on the query shape there, then paste the finished document into your integration.

Pagination & nested collections

List arguments are clamped server-side; values outside the clamp fall back to the defaults below.

Field	Default	Max
`contacts(limit:)`	25	100
`conversations(limit:)`	25	100
`segments(limit:)`	25	100
`Contact.conversations(limit:)`	10	50
`Contact.messages(limit:)`, `Conversation.messages(limit:)`	20	100

Top-level lists page by offset (0 starts at the newest row by creation time; conversations order by last activity). Nested collections take a limit only — page their parent (e.g. further conversations) rather than the nested list itself. Tenant isolation: execution is always scoped to the calling key’s tenant. A GraphQL request can never reach another tenant’s data, and there is no cross-tenant query mode.

Walkthrough A — export a contact with all conversations and messages

One REST join costs three sequential requests (GET /contacts/:id, GET /conversations?contact_id=…, then GET /messages?conversation_id=… per conversation). The GraphQL version is a single request:

query ContactExport($id: ID!) {
  contact(id: $id) {
    id
    externalId
    displayName
    phone
    email
    lifecycleStage
    conversations(limit: 50) {
      id
      channel
      status
      lastMessageAt
      messages(limit: 100) {
        id
        direction
        body
        status
        sentAt
      }
    }
  }
}

curl -X POST https://api.orbit.devotel.io/api/v1/developer/graphql \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "query": "…", "variables": { "id": "contact_01JABC..." }, "operationName": "ContactExport" }'

The response nests each conversation’s messages under its conversation:

{
  "data": {
    "contact": {
      "id": "contact_01JABC...",
      "displayName": "Ada Meyer",
      "conversations": [
        {
          "id": "conv_01KXYZ...",
          "channel": "sms",
          "status": "open",
          "messages": [
            { "id": "msg_01HXYZ...", "direction": "inbound", "status": "delivered" }
          ]
        }
      ]
    }
  }
}

If the contact doesn’t exist, data.contact is null with no errors entry — check for null before unpacking.

Walkthrough B — traverse to a segment’s contacts

Resolve segment ids, then pull contacts on the members’ lifecycle stage — the query asks for the exact shape so the response carries just the fields you consume:

query SegmentExport($limit: Int) {
  segments(limit: $limit) {
    id
    name
    description
    contactCount
  }
  contacts(lifecycleStage: "customer", limit: 100) {
    id
    displayName
    phone
    company
  }
}

For a deeper traversal anchor the segment to one contact and walk out through that contact’s conversations and message bodies — contact(id:) → conversations → messages — all in the same request, still one round-trip end to end.

Errors & failure modes

GraphQL responses differ from the REST envelope in one important way: a query-level failure is not an HTTP error. Parse failures, validation rejections, and per-field resolver errors all return 200 OK with an errors array next to data (which is null or partially populated on failure). Transport-level failures — auth, body validation, rate limits — still come back as HTTP error codes.

Failure	Status	Shape	Fix
Missing/invalid API key or insufficient role	`401`/`403`	REST `error` envelope	Check `Settings → API Keys`; the key needs `owner`/`admin`/`developer`
Body fails validation (empty `query`, `query` over 20 KB, wrong field types)	`422` `VALIDATION_ERROR`	REST envelope with `details.issues`	Send `{ query, variables?, operationName? }` as JSON
Query won’t parse (syntax error)	`200`	`errors: [{ "message": "Syntax error: …" }]`	Fix the document syntax
Query too deep or too complex	`200`	`errors: [{ "Query is too complex: …" }]`	Reduce nesting, lower `limit`s, drop aliasing repeats
Unknown field on a type	`200`	per-field `errors` entry	Check the field against the SDL endpoint
Rate limit exceeded	`429` `RATE_LIMITED`	REST envelope with `details.retry_after`	Respect the retry hint; see below

Use REST error-handling patterns for the HTTP-level failures, and treat the errors array as the GraphQL-level failure channel.

Rate limits

Both endpoints share the tenant-scoped authenticated write bucket — 60 requests per minute per tenant. Buckets are per tenant, so a heavy integration cannot crowd out your dashboard, but your own scripts share the same window. On 429, read details.retry_after (seconds) and back off instead of retrying on a fixed schedule. Cheap request shapes stay cheap: batch the reads you need into one nested query rather than hammering the endpoint with single-field requests.

Frequently asked questions

Can I write through GraphQL?

No. The surface is read-only — there are no mutations. Sends, updates, and administrative actions all stay on the REST API.

Why did my query return `200` with an `errors` array?

That’s the GraphQL-over-HTTP convention: the request was well-formed at the HTTP layer, and the failure is inside the query. Read errors[0].message; common causes are a syntax error, an unknown field, or the complexity cap.

How do I list more than 100 conversations?

Page the parent: conversations(limit: 100, offset: …) for the next batch. Nested collections carry at most one page per parent by design — they’re shaped reads, not bulk export. For bulk export use the REST list endpoints with pagination.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Query related records in one request with GraphQL

Query the GraphQL surface

When to use GraphQL vs REST

Auth & roles

Your first request

Schema introspection

Variables, operation names, and limits

Prototype in the dashboard Explorer

Walkthrough A — export a contact with all conversations and messages

Walkthrough B — traverse to a segment’s contacts

Errors & failure modes

Rate limits

Frequently asked questions

Can I write through GraphQL?

Why did my query return `200` with an `errors` array?

How do I list more than 100 conversations?

See also

​Query the GraphQL surface

​When to use GraphQL vs REST

​Auth & roles

​Your first request

​Schema introspection

​Variables, operation names, and limits

​Prototype in the dashboard Explorer

​Pagination & nested collections

​Walkthrough A — export a contact with all conversations and messages

​Walkthrough B — traverse to a segment’s contacts

​Errors & failure modes

​Rate limits

​Frequently asked questions

​Can I write through GraphQL?

​Why did my query return 200 with an errors array?

​How do I list more than 100 conversations?

​See also

Query the GraphQL surface

When to use GraphQL vs REST

Auth & roles

Your first request

Schema introspection

Variables, operation names, and limits

Prototype in the dashboard Explorer

Pagination & nested collections

Walkthrough A — export a contact with all conversations and messages

Walkthrough B — traverse to a segment’s contacts

Errors & failure modes

Rate limits

Frequently asked questions

Can I write through GraphQL?

Why did my query return `200` with an `errors` array?

How do I list more than 100 conversations?

See also