About:
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.
This guide assumes a basic understanding of coding and GraphQL. For general GraphQL learning resources, see https://graphql.org/learn/.
Schema & Documentation
Interactive docs: https://YOURTENANTNAME.echoglobal.org/graphql-docs (requires login as an admin)
The schema updates automatically as new fields and queries are added.
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.
Making Your First Query
Send a POST request to https://YOURTENANTNAME.echoglobal.org/graphql with your API token in the Authorization header.
Example using curl:
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). Each connection returns up to 250 items per page by default.
Use the "first" argument to control page size, and "after" with the "endCursor" value to fetch the next page.
Example response structure:
{
"data": {
"clients": {
"pageInfo": {
"endCursor": "MjA",
"hasNextPage": true
},
"edges": [
{
"node": { "id": "1", "name": "..." }
}
]
}
}
}
Fetching All Pages
This script pages through all results and writes them to a JSON file:
#!/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"
Usage:
bash script.sh > result.json
This is a basic example; customize the query fields and filtering to match your needs.
Claiming and Closing Conversations
The API can also work conversations the way a responder does in Echo. Each of these operations acts for the user whose ID you pass as userId. The interactive docs list every argument and field.
Mutations:
claimConversation claims a conversation (conversationId) for that user, the same as claiming it from the inbox.
closeConversation closes a conversation (conversationId) as that user. To complete it with an outcome at the same time, add outcomeId (with optional notes), or set useDefaultOutcome to true to use your ministry's default outcome.
Queries:
conversationInbox returns the unclaimed inbox that user sees, limited to the last 60 days.
claimedConversations returns the conversations that user has claimed.
These two queries return conversations only. Phone calls are not included.