Gladly API (1.0)

Download OpenAPI specification:Download

Introducing the Gladly API

At Gladly, we believe that customer service is best when it's a conversation. That means more than just helping customers with one-off questions or issues: it's about making them feel known, valued, and respected for the individuals they are.

The Gladly API was built to help facilitate those relationships, providing agents with the rich customer context they need to deliver seamless experiences that make customers feel like they're more than just a number in a sea of others.

Overview

You can integrate easily with Gladly by calling Gladly's REST API and implementing the Lookup API to provide data from your own services.

Some examples of what you do through Gladly APIs include managing customer profile data, interacting with a customer's timeline, providing the latest information about a customer's orders, and more.

REST API

Clients can access the REST API via HTTPS at your organization's Gladly domain (e.g. https://{organization}.gladly.com).

Resources follow REST semantics and utilize industry-standard HTTP verbs, response codes, and authentication schemes. In addition, all responses and payloads are in JSON with consistent error codes and formats.

Lookup API

The Gladly Lookup API allows your organization to provide data services to power the agent's experience with a complete view of your customers' information, transactions, and activity. You can provide a web service that implements the Lookup API and Gladly will call it when that data is needed.

Like the REST API, the Lookup API is specified using REST semantics, and exchanges JSON requests and responses authenticated and signed with secure keys.

Gladly will perform lookups when certain activities occur within Gladly, such as when a customer's profile is loaded.

A detailed overview of Lookup Adaptor architecture, requests, resposnes and more can be found here.

Testing

Test the myriad possibilities of the Gladly API in a safe, secure space. We'll enable the Gladly API in a separate sandbox environment, so you can experiment freely without impacting your production environment (or vice versa).

Your sandbox environment is accessible at https://{organization}.gladly.qa, where organization is your company name. For specific API endpoints, see documentation below.

Getting Started

Think of this section as getting the keys to unlocking your access to the Gladly APIs. First, you'll need to set up an account with the necessary API permissions. With these permissions, you can then go on to create the API Token(s) you need to access Gladly's API resources.

Permissions

Gladly Administrators can set API permissions on an agent-by-agent basis. We'll discuss how this maps to API access in the section on authentication below.

To allow a user to create API tokens and access the API:

  1. Log in to your Gladly instance.
  2. Open the menu on the top left-hand corner of the page.
  3. Navigate to Settings > *Users
  4. Search and click the user profile you wish to give access to.
  5. You'll see a permission called API User. Select it, while making sure to keep the user's Agent role intact.
  6. Hit Save to give access.

Agent profile screen

We recommend creating a dedicated user to make API calls, whose account won't be used for agent and organization management. This will help you with any future audits of API activity vs. agent activity.

Creating API Tokens

You must create an API token to access Gladly API resources (see above Permissions). If your profile already has access to the API User permission, you'll see a menu item titled More settings. Click More settings:

API Token Menu

Click API Tokens, then the Create Token button on the upper right-hand corner of the page:

API Token Add

A token will be generated and named, by default, New Token (though depending on whether you have existing tokens, it may be named New Token 2, or New Token 3, etc.). You can rename the token to something more easily referenceable by clicking the name to edit.

This token will be associated with your agent profile, which we refer to as the API User in this document.

API Token View

For security purposes, you'll only see a new token once before you navigate away from the page.

Replacing/Rotating API Tokens

Should you lose this token, or wish to rotate your application keys, you can do the following:

  1. Generate a new token.
  2. Store the new token in a secure location.
  3. Delete the old token.
  4. Update your applications/scripts with the new token.

Authentication

BasicAuth

Gladly API uses token-based Basic Authentication. API tokens are associated with designated Gladly users. To create and use an API token, your user must have the API User permission. An API token can be used to perform any API request without restriction.

user name password
agent email API token

The credentials must be passed via an Authorization HTTP header. All requests must be made over HTTPS.

curl -u user@organization.com:$GLADLY_API_TOKEN \
https://organization.gladly.com/api/v1/organization
Security Scheme Type HTTP
HTTP Authorization Scheme basic

Agents

An Agent represents the user profile of a person who helps customers in Gladly. The API allows you to lookup Agents who participated in conversations with customers.

List Agents

Returns a list of agents.

Responses

200

Agents

get /api/v1/agents
https://organization.gladly.com/api/v1/agents

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get Agent

Get an agent profile by their unique id.

path Parameters
agentId
required
string
Example: WmeA3Y51Q5ayCAaZ1AotIA

id of the agent

Responses

200

Agent

get /api/v1/agents/{agentId}
https://organization.gladly.com/api/v1/agents/{agentId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "WmeA3Y51Q5ayCAaZ1AotIA",
  • "name": "Amy Agent",
  • "emailAddress": "amy.agent@company.com"
}

Get Agent CallRecorder

Get an agent call recording status.

path Parameters
agentId
required
string
Example: WmeA3Y51Q5ayCAaZ1AotIA OR agent@customer.com

Gladly ID or Gladly email address of the agent

Responses

200

CallRecorder

404

Agent not found

get /api/v1/agents/{agentId}/call-recorder
https://organization.gladly.com/api/v1/agents/{agentId}/call-recorder

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "agentId": "WmeA3Y51Q5ayCAaZ1AotIA",
  • "customerId": "ZcyobierQhucTS5GV1R2Fw",
  • "conversationItemId": "g6UatsvAQC69AcDpOKF-yQ",
  • "recording": "true"
}

Update Agent CallRecorder

Update an agent's active call recording status. This API allows changing the recording property.

path Parameters
agentId
required
string
Example: WmeA3Y51Q5ayCAaZ1AotIA OR agent@customer.com

Gladly ID or Gladly email address of the agent

Request Body schema: application/json

JSON patch of CallRecorder

agentId
string

Id of the agent

customerId
string

Id of the customer on the call, if the agent is on a call. If the agent is not on a call this is omitted

conversationItemId
string

Id of the conversation item of the call, if the agent is on a call. If the agent is not on a call this is omitted

recording
boolean

If the call is currently being recorded or not

Responses

204

Call recording updated. If an agent is not on a call the update will do nothing.

404

Agent not found

patch /api/v1/agents/{agentId}/call-recorder
https://organization.gladly.com/api/v1/agents/{agentId}/call-recorder

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "recording": false
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "errors":
    {
    }
}

Answers

A Public Answer in Gladly represents a consumer-facing Answer.

Answers API allows you to search and retrieve Public Answers (created directly in the Gladly UI), which you can display in the Gladly Sidekick web widget, use to build your website's help center/FAQ page, or publish on any page on your website.

This API can be used without an API token because it only provides access to public content. You may also work with Gladly Support to enable CORS access so the API can be used directly from client-side javascript.

How a user creates a public answer in Gladly

How that answer is searched and displayed on the Sidekick web widget

Search public answers

Returns a list of answers that match the provided query string.

path Parameters
orgId
required
string
Example: ihKsWxiZCDVtXg1iwVmT9Q

id of your organization

You can look up the ID using the Get organization API.

query Parameters
q
string
Example: q=reset password

search term

lng
string
Example: lng=en-us

language code

audienceId
string
Example: audienceId=en-us

Audience ID. The Audience ID can be retrieved by going to Settings > Audiences in Gladly, then clicking on the Edit button next to the Audience in question. The ID will be in the page URL.

Responses

200

found answers

get /api/v1/orgs/{orgId}/answers/search?q=search+terms
https://organization.gladly.com/api/v1/orgs/{orgId}/answers/search?q=search+terms

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

List public answers

Returns the first 1000 public answers sorted alphabetically by name.

path Parameters
orgId
required
string
Example: ihKsWxiZCDVtXg1iwVmT9Q

id of your organization

You can look up the ID using the Get organization API.

query Parameters
lng
string
Example: lng=es-419

Language of the answers returned

Defaults to en-us

audienceId
string
Example: audienceId=ihKsWxiZCDVtXg1iwVmT9Q

Audience ID for answers returned - optional. The Audience ID can be retrieved by going to Settings > Audiences in Gladly, then clicking on the Edit button next to the Audience in question. The ID will be in the page URL.

Responses

200

answers

get /api/v1/orgs/{orgId}/answers?lng={lng}&audienceId={audienceId}
https://organization.gladly.com/api/v1/orgs/{orgId}/answers?lng={lng}&audienceId={audienceId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

List Help Center Answer Titles

Returns an array of answers configured in Help Center sections with their ID and name

path Parameters
orgId
required
string
Example: ihKsWxiZCDVtXg1iwVmT9Q

id of your organization

You can look up the ID using the Get organization API.

helpCenterId
required
string
Example: ihKsWxiZCDVtXg1iwVmT9Q

Help Center ID

You can look up the ID by going to Settings > Help Center in Gladly, then clicking on the 3 dots next to the Help Center and selecting Configure. Help Center ID will be in the URL

query Parameters
lng
string
Example: lng=es-419

Language of the answers returned

Defaults to en-us

audienceId
string
Example: audienceId=ihKsWxiZCDVtXg1iwVmT9Q

Audience ID for answers returned - optional. The Audience ID can be retrieved by going to Settings > Audiences in Gladly, then clicking on the Edit button next to the Audience in question. The ID will be in the page URL.

Responses

200

answers

get /api/v1/orgs/{orgId}/help-center/{helpCenterId}/answer-titles?lng={lng}&audienceId={audienceId}
https://organization.gladly.com/api/v1/orgs/{orgId}/help-center/{helpCenterId}/answer-titles?lng={lng}&audienceId={audienceId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
[