GraphQL API

The GraphQL API lets you pull reporting data out of Echo into your own reporting system. It also has a few mutations that write back to Echo, such as sending a message or claiming and closing a conversation.

4 minute read · Updated October 2026

About the GraphQL API

The GraphQL API lets you pull reporting data out of Echo into your own reporting system. It also has mutations that write back to Echo: sending a message, claiming and closing a conversation, creating and updating clients, and creating, updating and deleting tags.

This guide assumes a basic understanding of coding and GraphQL. For general GraphQL learning resources, see graphql.org/learn.

The GraphQL API is a paid add-on. Your ministry needs it switched on before a token can use it.

Schema and interactive docs

Every query, mutation and field is listed in the interactive docs at https://YOURTENANTNAME.echoglobal.org/graphql-docs. You need to be logged in as an admin to open them. Replace YOURTENANTNAME with your ministry's Echo address everywhere in this guide.

The schema updates automatically as new fields and queries are added, so the docs are always current.

Generating an API key

  1. Log in to your Echo instance with an admin account.
  2. Go to Admin > Email > API Tokens.
  3. Click Generate New Token in the top right.
  4. Copy and save the token. It is only displayed once.

Treat a token like a password. Anyone who has it can read your ministry's data. Keep it out of shared documents and code repositories, and generate a new one if it leaks.

Making your first query

Send a POST request to https://YOURTENANTNAME.echoglobal.org/graphql with your token in the Authorization header. This example asks for the first three clients and their phone numbers:

API_URL="https://YOURTENANTNAME.echoglobal.org/graphql"
API_TOKEN="your-token-from-admin-api-tokens"

curl -s -X POST "$API_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  -d '{
    "query": "{ clients(first: 3) { edges { node { id name clientPhones { number } } } } }"
  }'

Pagination

Results use cursor-based pagination (Relay-style). A connection returns up to 250 items per page. A few connections with large payloads cap lower.

  • Use first to set the page size.
  • Use after with the endCursor value from the previous page to get the next one.
  • Stop when hasNextPage is false.

A response looks like this:

{
  "data": {
    "clients": {
      "pageInfo": {
        "endCursor": "MjA",
        "hasNextPage": true
      },
      "edges": [
        { "node": { "id": "1", "name": "..." } }
      ]
    }
  }
}

Fetching all pages

This script pages through all conversations and prints them as JSON. It needs curl and jq.

#!/bin/bash
API_URL="https://YOURTENANTNAME.echoglobal.org/graphql"
API_TOKEN="your-token-from-admin-api-tokens"
END_CURSOR=""
ALL_RESULTS="[]"

while true; do
  AFTER_ARG=""
  if [ -n "$END_CURSOR" ]; then
    AFTER_ARG="after: \"$END_CURSOR\""
  fi

  RESPONSE=$(curl -s -X POST "$API_URL" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_TOKEN" \
    -d "{
      \"query\": \"{ conversations(${AFTER_ARG:+$AFTER_ARG}) { pageInfo { endCursor hasNextPage } edges { node { id topic createdAt client { id name email clientPhones { number } } } } } }\"
    }")

  HAS_NEXT=$(echo "$RESPONSE" | jq '.data.conversations.pageInfo.hasNextPage')
  END_CURSOR=$(echo "$RESPONSE" | jq -r '.data.conversations.pageInfo.endCursor')
  PAGE=$(echo "$RESPONSE" | jq '.data.conversations.edges')
  ALL_RESULTS=$(echo "$ALL_RESULTS" "$PAGE" | jq -s 'add')

  if [ "$HAS_NEXT" != "true" ]; then
    break
  fi
done

echo "$ALL_RESULTS"

Save it as script.sh and run it:

bash script.sh > result.json

This is a basic example. Change the query fields and add filtering to match what you need.

Claiming and closing conversations

The API can also work conversations the way a responder does in Echo. Each operation acts for the user whose ID you pass as userId. The interactive docs list every argument and field.

NameTypeWhat it does
claimConversationMutationClaims the conversation (conversationId) for that user, the same as claiming it from the inbox.
closeConversationMutationCloses the conversation (conversationId) as that user. To close it with an outcome, add outcomeId (and optional notes), or set useDefaultOutcome to true to use your ministry's default outcome.
conversationInboxQueryReturns the unclaimed inbox that user sees, limited to the last 60 days.
claimedConversationsQueryReturns the conversations that user has claimed.

The two queries return conversations only. Phone calls are not included.

Limits

The GraphQL add-on includes these limits:

LimitValue
Tokens that can use GraphQL5
Requests300 per minute
Date range in one query31 days
Records deep into a paginated list10,000
Items per page250 (some connections are lower)

Need more? Contact us about a custom plan.

When something goes wrong

You seeWhat to do
A 429 response saying you exceeded the rate limitWait 60 seconds, then try again. Slow your script down, or ask for fewer items per request.
An error about access, or no dataCheck that the header reads Authorization: Bearer followed by your token, that the token was copied in full, and that it has not been deleted.
A query that stops partway through a long listPage with after and endCursor, and keep each query inside the 31-day date range.

Did this answer your question?

  1. External Integrations

    You may have had a conversation with someone outside of Echo that you want to capture the details and store them inside your Echo account for tracking purposes.

  2. Zapier Integration

    The Echo Global Zapier Integration provides a way to push or pull certain information from Echo into another Application that you may be using.

  3. Admin: Tenant Settings

    An admin sets the ministry's time zone, how pictures and other multimedia appear in conversations, and whether 2-factor authentication is required for every user. Find it at Admin, Settings, Tenant Settings.

Still stuck?

Send us your Echo address and a screenshot of what you are seeing, and it goes to somebody who can look at your account.