GraphQL API
About:
The GraphQL Integration is designed to allow customers to pull their own reporting data out of Echo to be used in their own reporting system of choice. Currently this is a read-only option (API can pull data from Echo, but cannot not write updates back into Echo).
Instructions assume basic level of understanding with coding and GraphQL.
For additional information about how to use GraphQL, you can go to https://graphql.org/learn/
https://INSERTTENANTNAME.echoglobal.org/schema.graphql contains our graphql schema, open it as you would any text file.
Generating an API Key
You will need to create an API Key in Echo to be used in your script:
With an admin account, login to your Echo Global instance.
Go to Admin -> Email -> API Tokens and then click on the "Generate New Token" button in the top right.
Your API token will be generated and displayed only once. Save this token somewhere secure.
Using Graph QL to create the API
To access the graphql api, you can use this curl script:
API_URL="https://INSERTTENANTNAME.echoglobal.org/graphql"
API_TOKEN="copy from admin/api_tokens"
QUERY=$(cat << EOF
{ "query": "{ \
clients(first: 3) { \
edges { \
node { \
id \
name \
clientPhones { \
number \
} \
} \
} \
} \
}"}
EOF
)
curl -X POST \
"$API_URL" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_TOKEN" \
--data "$QUERY"
Note: The result is paginated, displaying only 20 nodes at a time. This pagination allows us to manage large datasets effectively.
The following script demonstrates how to fetch more than 20 results and store them in a JSON file for further processing:
#!/bin/bash
endCursor=""
OUTPUT_JSON_ARRAY="[]"
while : ; do
QUERY=$(cat << EOF
{ "query": "{ \
conversations(after: \"$endCursor\") { \
pageInfo { endCursor hasNextPage } \
edges { \
cursor \
node { \
id \
topic \
createdAt \
client { \
id \
name \
email \
clientPhones { \
number \
} \
} \
} \
} \
} \
}"}
EOF
)
RESPONSE=$(curl -s -X POST "$API_URL" -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" --data "$QUERY")
hasNextPage=$(echo $RESPONSE | jq '.data.conversations.pageInfo.hasNextPage')
endCursor=$(echo $RESPONSE | jq -r '.data.conversations.pageInfo.endCursor')
CURRENT_PAGE=$(echo $RESPONSE | jq '.data.conversations.edges')
OUTPUT_JSON_ARRAY=$(echo $OUTPUT_JSON_ARRAY $CURRENT_PAGE | jq -s 'add')
if [[ $hasNextPage != "true" ]]; then
break
fi
done
echo $OUTPUT_JSON_ARRAY
----------------------------------------------
$ touch result.json
$ bash script.sh > result.json
This script is a basic example of how to handle paginated GraphQL responses. It can be further customized to suit specific needs.
https://INSERTTENANTNAME.echoglobal.org/schema.graphql contains our graphql schema, open it as you would any text file.
