logo
Documentation Powered by ReDoc

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.

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 up the menu on the top left-hand corner of the page
  3. Navigate to Settings > Users
  4. Search and click on 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 new menu item titled API Tokens:

API Token Menu

Click on API Tokens, then the Add 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 it.

This token will be associated with your agent profile, which we will 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.

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.

Get Agent

Get an agent profile by their unique id.

path Parameters
agentId
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"
}

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 as it only provides access to public content. You may also work with your Customer Success Manager to enable CORS access so that 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
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

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
[
  • {
    }
]

Get public answer

Returns the answer with the provided id.

path Parameters
orgId
string
Example: ihKsWxiZCDVtXg1iwVmT9Q

id of your organization

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

answerId
string
Example: 1grfSzATQLa334VDLCWc4A

id of the answer

Responses

200

answer

get /api/v1/orgs/{orgId}/answers/{answerId}
https://organization.gladly.com/api/v1/orgs/{orgId}/answers/{answerId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "1grfSzATQLa334VDLCWc4A",
  • "name": "How to reset your password",
  • "bodyHtml": "<div><a href=\"/reset-password\">Click here</a> to reset your password</div>",
  • "language": "en-us"
}

Communications

Communications API enables you to programatically send messages to your customers via Gladly communications channels such as SMS.

Agent View

Agent View

Consumer View

Customer View

Send SMS

To send an SMS message to a customer specified by a mobile phone number.

Gladly can send outbound SMS messages globally. By default, your organization is set up to only allow access to your home country. To send SMS messages to other countries, please contact your Gladly Customer Success representative.

Request Body schema: application/json

SMS to send

customer
required
object (customer with mobile number)
from
required
string (mobile number)
body
required
string (SMS message)

Responses

200

the customer and conversation item ID

400

Invalid field(s) in request body

post /api/v1/communications/sms
https://organization.gladly.com/api/v1/communications/sms

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "customer":
    {
    },
  • "from": "+14152223316",
  • "body": "hello, this is a sample SMS message!"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "customerId": "gHufx-U3QqOmhvFuViceTw",
  • "conversationItemId": "pOVVdzweSumI4bFxjlT8LA"
}

Conversations

A Conversation in Gladly contains the timeline of activity for a customer including communications to and from your organization along with other internal and external activity. Conversations API enables you to interact with the customer conversation timeline.

Conversation Items

A number of different types of items may appear in a customer's timeline. Each is described below.

Item Type Create Read Delete
Chat Message No Yes No
Customer Activity Yes Yes Yes
Email No Yes No
Facebook Messenger Message No Yes No
Phone Call No Yes No
SMS Message No* Yes No
Topic Change No Yes No

* Messages can be sent through the Communications API.

Chat Message

Content of messages sent between Gladly and customers through Gladly Chat.

Customer Activity

Information about activities customers participated in, for example, emails they received, issues in another system, or customer statisfaction surveys they answered. These can be created through the API to bring in information from other systems. Adding an activity to the customer timeline is not customer facing. For example, posting an email activity to the timeline does not send an email to the customer. Customer Activity

Email

Content of emails sent between Gladly and customers.

Facebook Messenger Message

Content of messages sent between Gladly and customers on Facebook Messenger.

Phone Call

Information about phone calls that took place between Gladly and customers.

SMS Message

Content of SMS text messages sent between Gladly and customers. To send SMS messages to customers through the API, see Send SMS.

Task

Interacting with tasks through the conversations API is deprecated. Use Tasks API instead.

Topic Change

Record of an agent adding or removing a topic from a conversation in Gladly.

Create item

To add items to the timeline for a customer specified by identifying information. If the customer doesn't exist, a new customer profile is created.

Request Body schema: application/json

Conversation Item to create

id
string <= 50 characters

Unique conversation item id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included.

customer
required
object (Customer Specification)

Specifies the customer an item belongs to. You must provide exactly one of the values.

content
required
Customer Activity (object) or Task (deprecated) (object) (Conversation Item Content To Create)

Responses

200

The created item

400

Invalid field(s) in request body

409

Specified id is in use

post /api/v1/conversation-items
https://organization.gladly.com/api/v1/conversation-items

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "pOVVdzweSumI4bFxjlT8LA",
  • "customer":
    {
    },
  • "content":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "pOVVdzweSumI4bFxjlT8LA",
  • "customerId": "gHufx-U3QqOmhvFuViceTw",
  • "conversationId": "PmDVUfWfRjKuwb4VgA2zEA",
  • "timestamp": "2019-07-03T04:30:12.07Z",
  • "initiator":
    {
    },
  • "responder":
    {
    },
  • "content":
    {
    }
}

Get item

Returns the conversation item with the provided id.

path Parameters
itemId
required
string
Example: pOVVdzweSumI4bFxjlT8LA

id of the conversation item

Responses

200

conversation item

400

An item exists but is not supported by the API

404

An item with the given id could not be found

get /api/v1/conversation-items/{itemId}
https://organization.gladly.com/api/v1/conversation-items/{itemId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "pOVVdzweSumI4bFxjlT8LA",
  • "customerId": "gHufx-U3QqOmhvFuViceTw",
  • "conversationId": "PmDVUfWfRjKuwb4VgA2zEA",
  • "timestamp": "2019-07-03T04:30:12.07Z",
  • "initiator":
    {