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
- Log in to your Echo instance with an admin account.
- Go to Admin > Email > API Tokens.
- Click Generate New Token in the top right.
- 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
firstto set the page size. - Use
afterwith theendCursorvalue from the previous page to get the next one. - Stop when
hasNextPageisfalse.
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.jsonThis 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.
| Name | Type | What it does |
|---|---|---|
claimConversation | Mutation | Claims the conversation (conversationId) for that user, the same as claiming it from the inbox. |
closeConversation | Mutation | Closes 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. |
conversationInbox | Query | Returns the unclaimed inbox that user sees, limited to the last 60 days. |
claimedConversations | Query | Returns 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:
| Limit | Value |
|---|---|
| Tokens that can use GraphQL | 5 |
| Requests | 300 per minute |
| Date range in one query | 31 days |
| Records deep into a paginated list | 10,000 |
| Items per page | 250 (some connections are lower) |
Need more? Contact us about a custom plan.
When something goes wrong
| You see | What to do |
|---|---|
| A 429 response saying you exceeded the rate limit | Wait 60 seconds, then try again. Slow your script down, or ask for fewer items per request. |
| An error about access, or no data | Check 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 list | Page with after and endCursor, and keep each query inside the 31-day date range. |