Getting started

Understanding the tutorials

All request examples in our documentation use cURL notation.

You can refer to the API Reference for the complete OpenAPI specification.

All Global Relay API endpoints require HTTPS and conform to HTTP/1.1. Because the Conversation Archiving API is HTTP-based, it works with any language that has an HTTP library.

Enrolling your application

Before you can start calling the Conversation Archiving API, you must register your application and specify the data types you plan to archive. For more information about this process, contact your Global Relay Implementation engineer.

Authenticating your requests

As part of the enrolment process, you receive your secret API credentials, which must be kept secure and private. Never store these credentials in a code repository or include them in client-side code.

All Global Relay APIs require an access token to authenticate and authorize incoming requests.

To retrieve an access token from the /oauth2/token endpoint using your client credentials, make the following POST request:

curl -X POST "https://iam-oauth2.globalrelay.com/oauth2/token" \
 -H "Authorization: Basic <CREDENTIALS>" \
 -d "grant_type=client_credentials" \
 -d "scope=openid conversation file write"

We require that you send your client credentials in the Authorization header using the Basic Authentication scheme, as shown in the example. You do not need to transform or encode the supplied credentials in any way.

To use the Conversation Archiving API you will need to request a token with the scopes “openid”, “conversation” and “write”. If you also require use of the /files endpoint for sending conversation attachments, you must also request the “file” scope.

You will receive the following response payload:

{
    "access_token": "<YOUR_ACCESS_TOKEN>",
    "expires_in": "<EXPIRY_TIME>",
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "scope": "openid conversation file write",
    "not-before-policy": 0
}

In each request to the Conversation Archive API endpoints, pass the access token that corresponds to the data type being sent in the “Authorization: Bearer” HTTP header:

curl -X POST "https://conversations.api.globalrelay.com/v2/conversations" \
 -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Handling token expiry

The access token you fetch should be reused, and a new one should only be requested when the current token expires. The API returns a 403 error response for expired access tokens.

To obtain a new access token, make a new request to the /oauth2/token endpoint.

Revoking compromised credentials

Secure your client credentials with the same level of robustness as you would for usernames and passwords. If you suspect they are compromised, contact Global Relay as soon as possible to get them revoked and replaced.

Rate limits

API calls are limited to 1000 requests per minute for the /conversations endpoint, and 100 per minute for the /files endpoint. There is no limit to the amount of data you can send, but Global Relay may batch the data into separate messages in your Archive.