openapi: 3.0.1
info:
title: Gladly Agents Communications API
version: '1.0'
description: '# 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](#section/Overview/REST-API)
and implementing the [Lookup API](#section/Overview/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](https://help.gladly.com/developer/docs/lookup-adapter-introduction).
## 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](#/section/Getting-Started/Permissions).
With these permissions, you can then go on to create the [API Token(s)](#section/Getting-Started/Creating-API-Tokens) you need to access Gladly''s API [resources](#section/Overview/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](#section/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.
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](#/section/Getting-Started/Permissions)).
If your profile already has access to the **API User** permission, you''ll see a menu item titled **More settings**. Click **More settings**:
Click **API Tokens**, then the **Create Token** button on the upper right-hand corner of the page:
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.
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
<!-- ReDoc-Inject: <security-definitions> -->'
servers:
- url: https://{organization}.gladly.com/api/v1
description: Production
variables:
organization:
default: organization
description: Your Gladly organization subdomain
- url: https://{organization}.gladly.qa/api/v1
description: Sandbox
variables:
organization:
default: organization
description: Your Gladly QA organization subdomain
security:
- basicAuth: []
tags:
- name: Communications
description: 'Communications API enables you to programmatically send messages to your customers. These messages are non-routable and non-searchable.
### Agent View
### Consumer View
'
paths:
/api/v1/communications/sms:
post:
tags:
- Communications
summary: Send SMS
description: "To send an SMS message to a customer specified by a mobile phone number.\n\nGladly 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 [Gladly Support](https://help.gladly.com/implementation/docs/filing-a-support-issue) with a P4 designation.\n\nPlease be aware that:\n- Any automated outbound text messages **must** comply with carrier [acceptable use policies](https://help.gladly.com/docs/sms-compliance-requirements) (e.g.: if sending automated messages about order status, make sure customers can explicitly opt-in to text messages), including registering your SMS use cases carriers. \n- Text messages send in [segments](https://help.gladly.com/v1/docs/en/voice-and-sms-phone-number-costs) and you pay per segment. We highly recommend using the [segment calculator](https://twiliodeved.github.io/message-segment-calculator/) when crafting automated outbound text messages. \n- Each type of phone number has a [Message Segments per Second limit](https://support.twilio.com/hc/en-us/articles/115002943027-Understanding-Twilio-Rate-Limits-and-Message-Queues).\n"
operationId: sendSMS
requestBody:
description: SMS to send
content:
application/json:
schema:
title: SMS request body
required:
- customer
- from
- body
type: object
properties:
customer:
title: customer with mobile number
required:
- mobileNumber
type: object
properties:
mobileNumber:
$ref: '#/paths/~1api~1v1~1communications~1sms/post/requestBody/content/application~1json/schema/properties/from'
from:
title: mobile number
type: string
example: '+14152223316'
body:
title: SMS message
type: string
example: hello, this is an SMS message!
example:
customer:
mobileNumber: '+14152223000'
from: '+14152223316'
body: hello, this is a sample SMS message!
required: true
responses:
'200':
description: the customer and conversation item ID
content:
application/json:
schema:
type: object
properties:
customerId:
type: string
description: customer ID
example: gHufx-U3QqOmhvFuViceTw
conversationItemId:
type: string
description: conversation item ID of the SMS
example: pOVVdzweSumI4bFxjlT8LA
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/api/v1/communications/email:
post:
tags:
- Communications
summary: Send Email
description: 'Used to send an email messages to a customer specified by an email address.
Any items created using this API will not be considered part of a conversation, and are **non-routable** and **non-searchable** aside from the email address specified as part of the payload.
'
operationId: sendEmail
requestBody:
description: Email to send
content:
application/json:
schema:
title: Email request body
required:
- to
- from
- subject
- body
type: object
properties:
to:
description: Email addresses to send the email to. Currently, only one email address is supported. The email address and name will be used to find or create the customer.
type: array
items:
type: object
properties:
email:
type: string
name:
type: string
example:
email: jane.doe@example.com
name: Jane Doe
from:
description: Email address to send the email from. This must be a configured email address in your organization.
type: string
example: no-reply@gladly.com
subject:
type: string
description: Subject of the email. Must be less than 1000 characters.
example: This is a sample email message!
body:
description: Content of the email.
type: object
properties:
html:
type: string
description: HTML content of the email.
example: <div><p>This is a sample email message!</p><p>Best regards,<br>The Support Team</p></div>
text:
type: string
description: Plain text content of the email.
example: 'This is a sample email message!
Best regards,
The Support Team'
example:
html: <div><p>This is a sample email message!</p><p>Best regards,<br>The Support Team</p></div>
text: 'This is a sample email message!
Best regards,
The Support Team'
example:
to:
- email: jane.doe@example.com
name: Jane Doe
from: no-reply@gladly.com
subject: This is a sample email message!
body:
html: <div><p>This is a sample email message!</p><p>Best regards,<br>The Support Team</p></div>
text: This is a sample email message!\n\nBest regards,\nThe Support Team
required: true
responses:
'200':
description: the customer and conversation item ID
content:
application/json:
schema:
$ref: '#/paths/~1api~1v1~1communications~1sms/post/responses/200/content/application~1json/schema'
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
components:
schemas:
Errors:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Error'
example:
- attr: content
code: blank
detail: content cannot be blank
Error:
type: object
properties:
attr:
type: string
description: Identifies the field causing the error
code:
type: string
description: Code indicating the error type
detail:
type: string
description: More details describing what went wrong
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: '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.
```shell
curl -u user@organization.com:$GLADLY_API_TOKEN \
https://organization.gladly.com/api/v1/organization
```
'
basicAuth:
type: http
scheme: basic
description: HTTP Basic auth — username is the API user email; password is the API token. Requires the "API User" permission.
x-tagGroups:
- name: REST API
tags:
- Agents
- Public Answer
- Answer Management
- Audiences
- Business Hours
- Communications
- Conversations
- Customers
- Events
- Export
- Freeform Topics
- Inboxes
- Organization
- Proactive Conversations
- Reports
- Tasks
- Teams
- User Identity
- Topics
- Webhooks
- name: Webhooks
tags:
- Summary
- Payloads
- name: Lookup API
tags:
- Customer Lookup
- name: Resources
tags:
- Versioning
- Error Handling
- Rate Limit
- Rich Content
- Launching Soon